jj-stack 0.1.0__py3-none-any.whl

jj_stack/commands/cleanup/shared.py

@@ -0,0 +1,62 @@
+"""Shared cleanup command models, persistence, and rendering helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from jj_stack.bootstrap import CommandContext
+from jj_stack.github.resolution import (
+    GithubTarget,
+    UnresolvedGithubTarget,
+)
+from jj_stack.models.git import GitRemote
+from jj_stack.models.tracking import TrackedPR, TrackingState
+from jj_stack.ui import Message
+
+CleanupActionStatus = Literal["applied", "blocked", "planned", "skipped"]
+type CleanupBody = Message
+
+
+@dataclass(frozen=True, slots=True)
+class CleanupAction:
+    """One cleanup action that was planned, applied, blocked, or skipped."""
+
+    kind: str
+    status: CleanupActionStatus
+    body: CleanupBody
+
+
+@dataclass(frozen=True, slots=True)
+class CleanupResult:
+    """Rendered cleanup result for the selected repo."""
+
+    actions: tuple[CleanupAction, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedCleanup:
+    """Locally prepared cleanup inputs before any GitHub inspection."""
+
+    context: CommandContext
+    close_open_prs: bool
+    # None until plain cleanup proves it needs remote or GitHub state.
+    github_target: GithubTarget | UnresolvedGithubTarget | None
+    dry_run: bool
+    selected_change_ids: tuple[str, ...] | None
+    state: TrackingState
+
+    @property
+    def remote(self) -> GitRemote | None:
+        """The selected Git remote, once remote context is loaded and one resolved."""
+
+        return self.github_target.remote if self.github_target is not None else None
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedCleanupChange:
+    """Locally prepared cleanup state for one complete tracked PR."""
+
+    candidate: TrackedPR
+    has_mutable_copy: bool
+    stale_reason: str | None

jj_stack/commands/cleanup/stale.py

@@ -0,0 +1,79 @@
+"""Staleness detection for tracked stack changes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from jj_stack.bootstrap import CommandContext
+from jj_stack.stack.repo import observe_repo_paths
+
+
+@dataclass(frozen=True, slots=True)
+class LocalCleanupObservation:
+    """Why one tracked change is stale locally, if it is."""
+
+    has_mutable_copy: bool
+    stale_reason: str | None
+
+
+def local_cleanup_observations(
+    *,
+    change_ids: tuple[str, ...],
+    context: CommandContext,
+) -> dict[str, LocalCleanupObservation]:
+    jj_client = context.jj_client
+    matched_commits = jj_client.query_commits_by_change_ids(change_ids)
+    observations: dict[str, LocalCleanupObservation] = {}
+
+    for change_id in change_ids:
+        commits = matched_commits.get(change_id, ())
+        if not commits:
+            observations[change_id] = LocalCleanupObservation(
+                has_mutable_copy=False,
+                stale_reason="no visible local copy remains",
+            )
+            continue
+        if len(commits) > 1:
+            observations[change_id] = LocalCleanupObservation(
+                has_mutable_copy=any(not commit.immutable for commit in commits),
+                stale_reason="multiple visible commits still share that change ID",
+            )
+            continue
+
+        change = commits[0]
+        if not change.is_submittable():
+            observations[change_id] = LocalCleanupObservation(
+                has_mutable_copy=not change.immutable,
+                stale_reason="local change is no longer an active stack member",
+            )
+            continue
+
+        observations[change_id] = LocalCleanupObservation(
+            has_mutable_copy=True,
+            stale_reason=None,
+        )
+
+    candidate_changes = tuple(
+        commits[0]
+        for change_id in change_ids
+        if observations[change_id].stale_reason is None
+        for commits in (matched_commits.get(change_id, ()),)
+        if commits
+    )
+    if not candidate_changes:
+        return observations
+    repo_paths = observe_repo_paths(
+        jj_client=jj_client,
+        descendant_of=tuple(change.commit_id for change in candidate_changes),
+        state=context.state_store.load(),
+    )
+    supported_commit_ids = {
+        change.commit_id for path in repo_paths.paths for change in path.stack.changes
+    }
+    for change in candidate_changes:
+        if change.commit_id not in supported_commit_ids:
+            observations[change.change_id] = LocalCleanupObservation(
+                has_mutable_copy=True,
+                stale_reason="local change is no longer part of a stack",
+            )
+    return observations

jj_stack/commands/doctor.py

@@ -0,0 +1,358 @@
+"""Check `jj-stack`'s configuration and connectivity.
+
+Checks PR-branch fetch settings, visible PR bookmarks, leftovers from interrupted
+checkout or sync commands, remote selection, GitHub connectivity, authentication, and trunk
+discovery. By default, it only reports problems. Pass `--fix` to also apply the local repairs it
+can make safely. Currently, the only automatic repair is reserving the PR-branch namespace
+in the remote's fetch configuration. The command never changes GitHub.
+
+Exit status is 0 unless a check fails; warnings and problems repaired by `--fix` do not count as
+failures. When a check fails, the command exits 1 and names a recovery command when `jj-stack` can
+determine one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from contextlib import nullcontext
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import jj_stack.console as console
+import jj_stack.ui as ui
+from jj_stack.bootstrap import CommandContext, bootstrap_context
+from jj_stack.errors import CliError, error_message
+from jj_stack.github.auth import github_token, github_token_from_env
+from jj_stack.github.client import (
+    GithubClientError,
+    build_github_client,
+)
+from jj_stack.github.resolution import (
+    GithubRepoAddress,
+    parse_github_repo,
+    select_submit_remote,
+)
+from jj_stack.github.stack_availability import github_stacks_unavailable_error
+from jj_stack.jj.cli_args import JjCliArgs
+from jj_stack.models.git import GitRemote
+from jj_stack.models.github import GithubRepo
+from jj_stack.pr_branch_namespace import current_pr_branch_namespace
+from jj_stack.state.operation_lock import acquire_operation_lock
+from jj_stack.ui import Message
+
+HELP = "Check repo setup and GitHub connectivity"
+
+type CheckDetail = Message
+
+
+@dataclass(slots=True, frozen=True)
+class CheckResult:
+    label: str
+    status: Literal["ok", "warn", "fail", "fixed", "skip"]
+    detail: CheckDetail
+
+
+def doctor(
+    *,
+    cli_args: JjCliArgs,
+    debug: bool,
+    fix: bool,
+    repo: Path | None,
+) -> int:
+    """CLI entrypoint for `doctor`."""
+    context = bootstrap_context(
+        repo=repo,
+        cli_args=cli_args,
+        debug=debug,
+    )
+    operation = (
+        acquire_operation_lock(
+            context.state_store.require_writable(),
+            command="doctor --fix",
+        )
+        if fix
+        else nullcontext()
+    )
+    with operation, console.spinner(description="Running checks"):
+        results = asyncio.run(_run_checks(context=context, fix=fix))
+    console.output(_results_table(results))
+    return 1 if any(r.status == "fail" for r in results) else 0
+
+
+async def _run_checks(
+    *,
+    context: CommandContext,
+    fix: bool,
+) -> list[CheckResult]:
+    results: list[CheckResult] = []
+
+    # Check 1: Git remote selection
+    remote_result, selected_remote = _check_git_remote(context=context)
+    results.append(remote_result)
+
+    if selected_remote is None:
+        results.extend(
+            _skipped(
+                "PR branch fetch",
+                "checkout/sync leftovers",
+                "GitHub remote",
+                "GitHub auth",
+                "connectivity",
+                "GitHub stacks",
+                "trunk branch",
+            )
+        )
+        return results
+
+    results.append(
+        _check_pr_branch_fetch_isolation(context=context, fix=fix, remote=selected_remote)
+    )
+    results.append(_check_pr_branch_temp(context=context))
+
+    # Check 2: GitHub remote parsing
+    github_result, parsed_repo = _check_github_remote(selected_remote)
+    results.append(github_result)
+
+    if parsed_repo is None:
+        results.extend(_skipped("GitHub auth", "connectivity", "GitHub stacks", "trunk branch"))
+        return results
+
+    # Check 3: GitHub auth
+    auth_result, token = _check_github_auth()
+    results.append(auth_result)
+
+    if token is None:
+        results.extend(_skipped("connectivity", "GitHub stacks", "trunk branch"))
+        return results
+
+    # Checks 4-6: Connectivity, Stacks API availability, and trunk branch
+    connectivity_result, stacks_result, github_repo = await _check_github_connectivity(
+        parsed_repo=parsed_repo,
+    )
+    results.append(connectivity_result)
+    results.append(stacks_result)
+
+    if github_repo is not None:
+        results.append(_check_trunk_branch(github_repo))
+    else:
+        results.append(CheckResult("trunk branch", "skip", "connectivity failed"))
+
+    return results
+
+
+def _skipped(*labels: str) -> list[CheckResult]:
+    return [CheckResult(label, "skip", "prior check failed") for label in labels]
+
+
+def _check_git_remote(*, context: CommandContext) -> tuple[CheckResult, GitRemote | None]:
+    jj_client = context.jj_client
+    try:
+        remotes = jj_client.list_git_remotes()
+    except Exception as error:
+        return CheckResult("remote", "fail", f"could not list remotes: {error}"), None
+
+    if not remotes:
+        return (
+            CheckResult(
+                "remote",
+                "fail",
+                t"no Git remotes configured; run {ui.cmd('jj git remote add origin <url>')} "
+                t"to add one",
+            ),
+            None,
+        )
+
+    try:
+        remote = select_submit_remote(remotes)
+    except CliError as error:
+        return CheckResult("remote", "fail", error_message(error)), None
+
+    return CheckResult("remote", "ok", ui.bookmark(remote.name)), remote
+
+
+def _check_github_remote(remote: GitRemote) -> tuple[CheckResult, GithubRepoAddress | None]:
+    parsed = parse_github_repo(remote)
+    if parsed is None:
+        return (
+            CheckResult(
+                "GitHub remote",
+                "fail",
+                t"remote {ui.bookmark(remote.name)} does not have fetch and push URLs "
+                t"for the same GitHub repo; use GitHub HTTPS or SSH URLs",
+            ),
+            None,
+        )
+    return CheckResult("GitHub remote", "ok", parsed.full_name), parsed
+
+
+def _check_pr_branch_fetch_isolation(
+    *,
+    context: CommandContext,
+    fix: bool,
+    remote: GitRemote,
+) -> CheckResult:
+    namespace = current_pr_branch_namespace()
+    visible = tuple(context.jj_client.visible_pr_bookmark_targets())
+    visible_detail: CheckDetail = (
+        t" Visible bookmarks remain: {ui.join(ui.bookmark, visible)}." if visible else ""
+    )
+    try:
+        isolation = context.jj_client.ensure_pr_branch_fetch_isolation(
+            remote=remote.name,
+            dry_run=not fix,
+        )
+    except CliError as error:
+        detail: CheckDetail = error_message(error)
+        if error.hint is not None:
+            detail = (detail, t" {error.hint}")
+        return CheckResult("PR branch fetch", "warn", detail)
+    if isolation.status == "required":
+        if isolation.problem == "missing":
+            problem_detail = (
+                t"missing {ui.code(namespace.fetch_refspec)} exclusion; ",
+                t"add it with {ui.cmd('jj-stack doctor --fix')}.",
+            )
+        elif isolation.problem == "duplicate":
+            problem_detail = (
+                t"found multiple {ui.code(namespace.fetch_refspec)} exclusions; ",
+                t"keep one with {ui.cmd('jj-stack doctor --fix')}.",
+            )
+        else:
+            raise AssertionError("required fetch isolation has no problem")
+        return CheckResult(
+            "PR branch fetch",
+            "warn",
+            (
+                problem_detail,
+                visible_detail,
+            ),
+        )
+    if visible:
+        return CheckResult(
+            "PR branch fetch",
+            "warn",
+            t"exclusion is configured; visible bookmarks remain: {ui.join(ui.bookmark, visible)}",
+        )
+    return CheckResult(
+        "PR branch fetch",
+        "fixed" if isolation.status == "applied" else "ok",
+        t"exactly one {ui.code(namespace.fetch_refspec)} exclusion",
+    )
+
+
+def _check_pr_branch_temp(*, context: CommandContext) -> CheckResult:
+    artifacts = context.jj_client.pr_branch_temp_artifacts()
+    if artifacts.ref_target is None and not artifacts.bookmark_targets:
+        return CheckResult("checkout/sync leftovers", "ok", "none")
+    return CheckResult(
+        "checkout/sync leftovers",
+        "warn",
+        t"leftovers from an interrupted command remain; rerun the interrupted "
+        t"{ui.cmd('jj-stack checkout --pull-request PR')} or "
+        t"{ui.cmd('jj-stack sync')} command to clear it",
+    )
+
+
+def _check_github_auth() -> tuple[CheckResult, str | None]:
+    env_token = github_token_from_env()
+    if env_token:
+        env_var = "GITHUB_TOKEN" if os.environ.get("GITHUB_TOKEN") else "GH_TOKEN"
+        return CheckResult("GitHub auth", "ok", f"token found ({env_var})"), env_token
+
+    # Env vars not set — try the gh CLI
+    token = github_token()
+    if token:
+        return CheckResult("GitHub auth", "ok", "token found (gh CLI)"), token
+
+    return (
+        CheckResult(
+            "GitHub auth",
+            "fail",
+            t"no token found; set GITHUB_TOKEN or run {ui.cmd('gh auth login')}",
+        ),
+        None,
+    )
+
+
+async def _check_github_connectivity(
+    *,
+    parsed_repo: GithubRepoAddress,
+) -> tuple[CheckResult, CheckResult, GithubRepo | None]:
+    async with build_github_client(repo=parsed_repo) as client:
+        try:
+            github_repo = await client.get_repo()
+        except GithubClientError as error:
+            return (
+                CheckResult(
+                    "connectivity",
+                    "fail",
+                    f"{parsed_repo.full_name}: {error.user_facing_reason()}",
+                ),
+                CheckResult("GitHub stacks", "skip", "connectivity failed"),
+                None,
+            )
+        except Exception as error:
+            return (
+                CheckResult(
+                    "connectivity",
+                    "fail",
+                    f"{parsed_repo.full_name}: request failed ({error})",
+                ),
+                CheckResult("GitHub stacks", "skip", "connectivity failed"),
+                None,
+            )
+        try:
+            await client.list_stacks()
+        except GithubClientError as error:
+            unavailable = github_stacks_unavailable_error(
+                error=error,
+                repo=parsed_repo.full_name,
+            )
+            detail: CheckDetail = (
+                (unavailable.message, t" {unavailable.hint}")
+                if unavailable is not None
+                else f"could not inspect stacks: {error.user_facing_reason()}"
+            )
+            stacks_result = CheckResult("GitHub stacks", "fail", detail)
+        else:
+            stacks_result = CheckResult("GitHub stacks", "ok", "Stacks API available")
+    return (
+        CheckResult(
+            "connectivity",
+            "ok",
+            f"reached {parsed_repo.full_name}",
+        ),
+        stacks_result,
+        github_repo,
+    )
+
+
+def _check_trunk_branch(github_repo: GithubRepo) -> CheckResult:
+    if github_repo.default_branch:
+        return CheckResult("trunk branch", "ok", github_repo.default_branch)
+    return CheckResult(
+        "trunk branch",
+        "warn",
+        t"GitHub repo has no default branch set; set a default branch on GitHub "
+        t"or configure {ui.revset('trunk()')} in jj",
+    )
+
+
+def _results_table(results: list[CheckResult]) -> ui.DataTable:
+    return ui.DataTable(
+        columns=(
+            ui.TableColumn("check"),
+            ui.TableColumn("status", no_wrap=True),
+            ui.TableColumn("detail"),
+        ),
+        rows=tuple(
+            (
+                result.label,
+                ui.status(result.status),
+                result.detail,
+            )
+            for result in results
+        ),
+    )

jj_stack/commands/in_use.py

@@ -0,0 +1,31 @@
+"""Check whether this repo contains valid `jj-stack` tracking data.
+
+Intended for scripts and automation, the command prints nothing and exits 0 when `jj-stack` is in
+use, 1 when it is not, and 11 for repo or tracking errors. It does not inspect the working
+copy, read GitHub, or create tracking.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from jj_stack.bootstrap import resolve_repo_root
+from jj_stack.errors import CliError, ProbeError
+from jj_stack.state.store import TrackingStore
+
+HELP = "Check whether this repo uses `jj-stack`"
+
+
+def in_use(*, repo: Path | None) -> int:
+    """CLI entrypoint for `in-use`."""
+
+    start = Path.cwd() if repo is None else repo
+    try:
+        if repo is not None and not repo.exists():
+            raise CliError(f"Repo path does not exist: {repo}")
+        if repo is not None and not repo.is_dir():
+            raise CliError(f"Repo path is not a directory: {repo}")
+        repo_root = resolve_repo_root(start)
+        return 0 if TrackingStore.for_repo(repo_root).is_in_use() else 1
+    except CliError as error:
+        raise ProbeError(error.message, hint=error.hint) from error