git-paoding 0.1.0__py3-none-any.whl

git_paoding/cli/main.py

@@ -0,0 +1,277 @@
+"""Command-line entry point."""
+
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+import click
+
+from git_paoding import __version__
+from git_paoding.agent_install import AgentInstallError, install_agent_skill
+from git_paoding.cli.facade import ApiFacade, CliFacade
+from git_paoding.cli.render import (
+    render_archive,
+    render_assign,
+    render_focus,
+    render_publish,
+    render_slice_added,
+    render_slice_list,
+    render_slice_removed,
+    render_slice_renamed,
+    render_status,
+)
+from git_paoding.core.model import AssignBatchRequest, PaodingError
+from git_paoding.github.gh_cli import GhCliBackend
+from git_paoding.gitio.runner import GitError
+
+
+def _backend(repo: Path) -> GhCliBackend:
+    return GhCliBackend(repo)
+
+
+_facade: CliFacade = ApiFacade()
+
+
+def _raise_cli_error(error: Exception) -> NoReturn:
+    raise click.ClickException(str(error)) from error
+
+
+@click.group(
+    epilog=(
+        "Exit codes: 0 = success/clean; 2 = action needed because attribution remains; "
+        "1 = operational error."
+    )
+)
+@click.version_option(version=__version__, prog_name="git-paoding")
+def main() -> None:
+    """Semantic review slicing for large agent-generated changes."""
+
+
+@main.group("agent")
+def agent_group() -> None:
+    """Install the packaged workflow for supported coding agents."""
+
+
+@agent_group.command("install")
+@click.option(
+    "--target",
+    "targets",
+    type=click.Choice(("codex", "claude"), case_sensitive=False),
+    multiple=True,
+    required=True,
+    help="Agent integration to install; repeat to install both.",
+)
+@click.option(
+    "--scope",
+    type=click.Choice(("user", "project"), case_sensitive=False),
+    default="user",
+    show_default=True,
+    help="Install for the current user or the current repository.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite packaged files when the destination has different contents.",
+)
+def agent_install_command(targets: tuple[str, ...], scope: str, force: bool) -> None:
+    """Install the bundled standalone skill without a plugin marketplace UI."""
+
+    try:
+        results = [
+            install_agent_skill(
+                target,  # type: ignore[arg-type]
+                scope,  # type: ignore[arg-type]
+                project_root=Path.cwd(),
+                force=force,
+            )
+            for target in targets
+        ]
+    except (AgentInstallError, OSError) as error:
+        _raise_cli_error(error)
+
+    for result in results:
+        action = "Installed" if result.changed else "Already installed"
+        click.echo(f"{action} {result.target} skill: {result.destination}")
+
+
+@main.command("init")
+@click.option("--base", required=True, help="Base ref to pin for this review session.")
+@click.option(
+    "--slice-prefix",
+    default="slice",
+    show_default=True,
+    help="Short identifier used in generated slice pull-request titles.",
+)
+def init_command(base: str, slice_prefix: str) -> None:
+    """Initialize a review session on the current branch."""
+
+    repo = Path.cwd()
+    try:
+        result = _facade.init_session(
+            repo,
+            base,
+            backend=_backend(repo),
+            slice_pr_prefix=slice_prefix,
+        )
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(render_status(result))
+
+
+@main.group("slice")
+def slice_group() -> None:
+    """Manage stable semantic slice identities."""
+
+
+@slice_group.command("add")
+@click.argument("slice_id")
+@click.option("--title", required=True, help="Human-facing slice title.")
+def slice_add_command(slice_id: str, title: str) -> None:
+    """Add one active slice."""
+
+    try:
+        result = _facade.add_slice(Path.cwd(), slice_id, title)
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(render_slice_added(result, slice_id=slice_id, title=title))
+
+
+@slice_group.command("list")
+def slice_list_command() -> None:
+    """List slices and their current diffstats without changing session state."""
+
+    try:
+        result = _facade.list_slices(Path.cwd())
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(render_slice_list(result))
+
+
+@slice_group.command("remove")
+@click.argument("slice_id")
+def slice_remove_command(slice_id: str) -> None:
+    """Remove one active slice identity."""
+
+    try:
+        result = _facade.remove_slice(Path.cwd(), slice_id)
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(render_slice_removed(result, slice_id=slice_id))
+
+
+@slice_group.command("rename")
+@click.argument("slice_id")
+@click.option("--title", required=True, help="New human-facing slice title.")
+def slice_rename_command(slice_id: str, title: str) -> None:
+    """Rename a slice while preserving its stable identity."""
+
+    try:
+        result = _facade.rename_slice(Path.cwd(), slice_id, title)
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(render_slice_renamed(result, slice_id=slice_id, title=title))
+
+
+@main.command("status")
+@click.option("--json", "as_json", is_flag=True, help="Emit the versioned JSON contract.")
+@click.option(
+    "--full",
+    is_flag=True,
+    help="Show complete changed-hunk previews (default: 3 changed lines).",
+)
+def status_command(as_json: bool, full: bool) -> None:
+    """Reconcile and report local attribution status."""
+
+    try:
+        result = _facade.get_status(Path.cwd(), full=full)
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(result.model_dump_json(indent=2) if as_json else render_status(result, full=full))
+    if result.unassigned_count or result.ambiguous_count:
+        raise click.exceptions.Exit(2)
+
+
+@main.command("assign")
+@click.argument("slice_id", required=False)
+@click.argument("selectors", nargs=-1)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Allow broad selectors to take atoms from another slice.",
+)
+@click.option(
+    "--batch",
+    type=click.Path(exists=True, dir_okay=False, allow_dash=True, path_type=Path),
+    help="Read the versioned batch JSON contract from a file, or '-' for stdin.",
+)
+def assign_command(
+    slice_id: str | None,
+    selectors: tuple[str, ...],
+    force: bool,
+    batch: Path | None,
+) -> None:
+    """Assign atoms using ids, paths, directories/globs, or Final line ranges."""
+
+    try:
+        if batch is not None:
+            if slice_id is not None or selectors:
+                raise PaodingError("--batch cannot be combined with a slice id or selectors")
+            if force:
+                raise PaodingError("--force cannot be combined with --batch; use batch JSON force")
+            source = sys.stdin.read() if str(batch) == "-" else batch.read_text(encoding="utf-8")
+            request = AssignBatchRequest.model_validate_json(source)
+            result = _facade.assign_batch(Path.cwd(), request)
+        else:
+            if slice_id is None or not selectors:
+                raise PaodingError(
+                    "Interactive assignment requires a slice id and at least one selector"
+                )
+            result = _facade.assign(Path.cwd(), slice_id, selectors, force=force)
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(render_assign(result))
+
+
+@main.command("focus")
+@click.argument("slice_id", required=False)
+@click.option("--clear", "clear_focus", is_flag=True, help="Clear the session-global focus.")
+def focus_command(slice_id: str | None, clear_focus: bool) -> None:
+    """Set a default slice prior for genuinely new atoms, or clear it."""
+
+    if (slice_id is None) == (not clear_focus):
+        _raise_cli_error(PaodingError("Pass exactly one slice id or --clear"))
+    target = None if clear_focus else slice_id
+    try:
+        result = _facade.set_focus(Path.cwd(), target)
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(render_focus(result, slice_id=target))
+
+
+@main.command("publish")
+@click.option("--json", "as_json", is_flag=True, help="Emit the versioned JSON contract.")
+@click.option("--remote", default="origin", show_default=True, help="Git remote for projections.")
+def publish_command(as_json: bool, remote: str) -> None:
+    """Publish or refresh Draft review projections idempotently."""
+
+    repo = Path.cwd()
+    try:
+        result = _facade.publish(repo, backend=_backend(repo), remote=remote)
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(result.model_dump_json(indent=2) if as_json else render_publish(result))
+    if result.action_needed:
+        raise click.exceptions.Exit(2)
+
+
+@main.command("archive")
+@click.option("--remote", default="origin", show_default=True, help="Git remote for projections.")
+def archive_command(remote: str) -> None:
+    """Archive slice PRs and generated refs after integration merges."""
+
+    repo = Path.cwd()
+    try:
+        result = _facade.archive(repo, backend=_backend(repo), remote=remote)
+    except (PaodingError, GitError, ValueError, OSError) as error:
+        _raise_cli_error(error)
+    click.echo(render_archive(result))

git_paoding/cli/render.py

@@ -0,0 +1,205 @@
+"""Human-readable terminal rendering of facade result models."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from git_paoding.core.model import (
+    AssignResult,
+    Atom,
+    AtomState,
+    PublishResult,
+    SliceStatus,
+    SliceSummary,
+    StatusResult,
+)
+
+_DEFAULT_PREVIEW_LINES = 3
+
+
+def _slice_lines(slices: Sequence[SliceSummary]) -> list[str]:
+    lines = ["  ID  STATUS  DIFFSTAT  PR  TITLE"]
+    if not slices:
+        lines.append("  (none)")
+        return lines
+    for slice_ in slices:
+        diffstat = slice_.diffstat
+        pr = f"#{slice_.pr_number}" if slice_.pr_number else "-"
+        lines.append(
+            f"  {slice_.id}  {slice_.status.value}  "
+            f"{diffstat.files_changed} files +{diffstat.additions} -{diffstat.deletions}  "
+            f"{pr}  {slice_.title}"
+        )
+    return lines
+
+
+def _preview_lines(preview: str, *, full: bool, indent: str) -> list[str]:
+    if not preview:
+        return []
+    source = preview.splitlines()
+    visible = source if full else source[:_DEFAULT_PREVIEW_LINES]
+    lines = [f"{indent}{line}" for line in visible]
+    if not full and len(source) > _DEFAULT_PREVIEW_LINES and visible[-1] != "…":
+        lines.append(f"{indent}…")
+    return lines
+
+
+def _atom_lines(atoms: Sequence[Atom], *, full: bool) -> list[str]:
+    if not atoms:
+        return ["  (none)"]
+    lines: list[str] = []
+    for atom in atoms:
+        owner = atom.owner or "-"
+        lines.append(
+            f"  {atom.atom_id}  {atom.state.value}  owner={owner}  {atom.path}  "
+            f"base:{atom.base_start}+{atom.base_len}  "
+            f"final:{atom.final_start}+{atom.final_len}"
+        )
+        lines.extend(_preview_lines(atom.preview, full=full, indent="    "))
+    return lines
+
+
+def _mutation_summary(result: StatusResult) -> list[str]:
+    active_count = sum(slice_.status is SliceStatus.ACTIVE for slice_ in result.slices)
+    return [
+        f"Session: {result.session.canonical_branch}",
+        f"Slices: {active_count} active",
+        (
+            f"Action needed: {result.unassigned_count} unassigned, "
+            f"{result.ambiguous_count} ambiguous"
+        ),
+        "Run `git-paoding status` to inspect atoms.",
+    ]
+
+
+def render_status(result: StatusResult, *, full: bool = False) -> str:
+    """Render session, slice, and atom attribution status."""
+
+    lines = [
+        f"Session: {result.session.canonical_branch}",
+        f"Base: {result.session.base_oid}",
+        f"Final: {result.session.last_final_oid or '-'}",
+        (
+            f"Action needed: {result.unassigned_count} unassigned, "
+            f"{result.ambiguous_count} ambiguous"
+        ),
+        f"Focus: {result.session.focus_slice or '-'}",
+        (
+            "Defaulted by focus: " + ", ".join(result.defaulted_atom_ids)
+            if result.defaulted_atom_ids
+            else "Defaulted by focus: (none)"
+        ),
+        "Slices:",
+    ]
+    lines.extend(_slice_lines(result.slices))
+    action_needed = [
+        atom for atom in result.atoms if atom.state in {AtomState.UNASSIGNED, AtomState.AMBIGUOUS}
+    ]
+    settled = [
+        atom
+        for atom in result.atoms
+        if atom.state not in {AtomState.UNASSIGNED, AtomState.AMBIGUOUS}
+    ]
+    lines.append("Action-needed atoms:")
+    lines.extend(_atom_lines(action_needed, full=full))
+    lines.append("Assigned/updated atoms:")
+    lines.extend(_atom_lines(settled, full=full))
+    return "\n".join(lines)
+
+
+def render_slice_list(result: StatusResult) -> str:
+    """Render only slice identities and diffstats for the read-only list verb."""
+
+    return "\n".join(
+        [f"Session: {result.session.canonical_branch}", "Slices:", *_slice_lines(result.slices)]
+    )
+
+
+def render_slice_added(result: StatusResult, *, slice_id: str, title: str) -> str:
+    """Render a concise acknowledgement for the slice-add mutation."""
+
+    return "\n".join(
+        [
+            f"Added slice: {slice_id}",
+            f"Title: {title}",
+            *_mutation_summary(result),
+        ]
+    )
+
+
+def render_slice_removed(result: StatusResult, *, slice_id: str) -> str:
+    """Render the delta from removing one slice."""
+
+    return "\n".join(
+        [
+            f"Removed slice: {slice_id}",
+            "Its atoms are now unassigned and must be reassigned before publishing.",
+            *_mutation_summary(result),
+        ]
+    )
+
+
+def render_slice_renamed(result: StatusResult, *, slice_id: str, title: str) -> str:
+    """Render the delta from renaming one slice."""
+
+    return "\n".join([f"Renamed slice: {slice_id}", f"Title: {title}", *_mutation_summary(result)])
+
+
+def render_focus(result: StatusResult, *, slice_id: str | None) -> str:
+    """Render the session-global focus delta."""
+
+    focus_line = f"Focus: {slice_id}" if slice_id is not None else "Focus: cleared"
+    return "\n".join([focus_line, *_mutation_summary(result)])
+
+
+def render_archive(result: StatusResult) -> str:
+    """Render a concise archive completion summary."""
+
+    archived_count = sum(slice_.status is SliceStatus.ARCHIVED for slice_ in result.slices)
+    return "\n".join(
+        [
+            f"Archived session: {result.session.canonical_branch}",
+            f"Slices archived: {archived_count}",
+        ]
+    )
+
+
+def render_assign(result: AssignResult) -> str:
+    """Render exactly which atoms were assigned or skipped."""
+
+    lines: list[str] = []
+    for record in result.assigned:
+        lines.append(f"assigned {record.atom_id} {record.path} -> {record.owner}")
+        if record.preview:
+            lines.extend(f"  {line}" for line in record.preview.splitlines())
+    for record in result.skipped:
+        lines.append(f"skipped {record.atom_id} {record.path} (owned by {record.previous_owner})")
+        if record.preview:
+            lines.extend(f"  {line}" for line in record.preview.splitlines())
+    return "\n".join(lines) if lines else "No atoms changed."
+
+
+def render_publish(result: PublishResult) -> str:
+    """Render action-needed status or per-slice publication outcomes."""
+
+    if result.action_needed:
+        if result.status is None:
+            return "Action needed before publishing."
+        return "Publish stopped before remote effects.\n" + render_status(result.status)
+
+    lines = [
+        (
+            f"Integration PR: #{result.integration_pr} {result.integration_pr_url}"
+            if result.integration_pr is not None
+            else "Integration PR: -"
+        )
+    ]
+    lines.append("Slices:")
+    if not result.slices:
+        lines.append("  (none)")
+    for slice_ in result.slices:
+        suffix = f" PR #{slice_.pr_number} {slice_.url}" if slice_.pr_number else ""
+        lines.append(f"  {slice_.slice_id}  {slice_.outcome.value}{suffix}")
+    if result.status is not None and result.status.defaulted_atom_ids:
+        lines.append("Defaulted by focus: " + ", ".join(result.status.defaulted_atom_ids))
+    return "\n".join(lines)

git_paoding/core/__init__.py

@@ -0,0 +1 @@
+"""Core domain package."""

git_paoding/core/diffatoms.py

@@ -0,0 +1,208 @@
+"""Construct persistent atom metadata and ephemeral replay payloads."""
+
+from __future__ import annotations
+
+import hashlib
+from collections import defaultdict
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+from git_paoding.core.model import Atom, AtomKind, AtomState
+from git_paoding.gitio.diffparse import RawDiffHunk
+
+_PREVIEW_LINE_LIMIT = 3
+
+
+@dataclass(frozen=True, slots=True)
+class ReplayAtom:
+    """An atom paired with the full text payload needed for replay.
+
+    ``Atom`` remains the compact persistent and contract-facing metadata type.
+    A ``ReplayAtom`` is deliberately ephemeral: callers reconstruct it from the
+    authoritative Base-to-Final diff whenever they need to replay content.
+    """
+
+    atom: Atom
+    removed_lines: tuple[bytes, ...]
+    added_lines: tuple[bytes, ...]
+
+
+def _line_bytes(line: str) -> bytes:
+    return line.encode("utf-8", errors="surrogateescape")
+
+
+def _hash_fields(fields: Iterable[bytes]) -> str:
+    """Hash length-delimited fields without concatenation ambiguities."""
+
+    digest = hashlib.sha256()
+    for field in fields:
+        digest.update(len(field).to_bytes(8, byteorder="big"))
+        digest.update(field)
+    return digest.hexdigest()
+
+
+def _text_content_hash(hunk: RawDiffHunk) -> str:
+    fields = [b"removed"]
+    fields.extend(_line_bytes(line) for line in hunk.removed_lines)
+    fields.append(b"added")
+    fields.extend(_line_bytes(line) for line in hunk.added_lines)
+    return _hash_fields(fields)
+
+
+def _whole_file_content_hash(hunk: RawDiffHunk) -> str:
+    """Fingerprint a non-text change from its authoritative Git tree entries."""
+
+    descriptors = (hunk.base_mode, hunk.base_oid, hunk.final_mode, hunk.final_oid)
+    if all(value is None for value in descriptors):
+        raise ValueError(f"whole-file hunk for {hunk.path!r} lacks Git object metadata")
+    return _hash_fields(
+        (
+            b"whole-file",
+            (hunk.base_mode or "missing").encode("ascii"),
+            (hunk.base_oid or "missing").encode("ascii"),
+            (hunk.final_mode or "missing").encode("ascii"),
+            (hunk.final_oid or "missing").encode("ascii"),
+        )
+    )
+
+
+def _atom_id_digest(
+    *,
+    path: str,
+    base_start: int,
+    base_len: int,
+    gap_seq: int,
+    content_hash: str,
+) -> str:
+    return _hash_fields(
+        (
+            path.encode("utf-8", errors="surrogateescape"),
+            str(base_start).encode("ascii"),
+            str(base_len).encode("ascii"),
+            str(gap_seq).encode("ascii"),
+            content_hash.encode("ascii"),
+        )
+    )
+
+
+def _kind(hunk: RawDiffHunk) -> AtomKind:
+    if hunk.is_binary or hunk.is_mode_change or hunk.is_symlink:
+        return AtomKind.WHOLE_FILE
+    if hunk.is_add_file:
+        return AtomKind.ADD_FILE
+    if hunk.is_delete_file:
+        return AtomKind.DELETE_FILE
+    return AtomKind.MODIFY
+
+
+def _whole_file_preview(hunk: RawDiffHunk) -> str:
+    def render(mode: str | None, oid: str | None) -> str:
+        if mode is None and oid is None:
+            return "missing"
+        short_oid = (oid or "unknown")[:8]
+        return f"{mode or 'unknown'} {short_oid}"
+
+    return (
+        f"whole-file: {render(hunk.base_mode, hunk.base_oid)} -> "
+        f"{render(hunk.final_mode, hunk.final_oid)}"
+    )
+
+
+def _preview(hunk: RawDiffHunk) -> str:
+    def safe_line(prefix: str, line: str) -> str:
+        raw_line = _line_bytes(line)
+        return prefix + raw_line.decode("utf-8", errors="replace")
+
+    changed_lines = [safe_line("-", line) for line in hunk.removed_lines]
+    changed_lines.extend(safe_line("+", line) for line in hunk.added_lines)
+    preview = "".join(changed_lines[:_PREVIEW_LINE_LIMIT])
+    if len(changed_lines) > _PREVIEW_LINE_LIMIT:
+        if preview and not preview.endswith("\n"):
+            preview += "\n"
+        preview += "…"
+    return preview
+
+
+def atomize_hunks(hunks: Sequence[RawDiffHunk]) -> tuple[ReplayAtom, ...]:
+    """Convert raw hunks to atoms plus non-persistent text replay payloads.
+
+    Pure insertions sharing a Base gap receive monotonically increasing
+    ``gap_seq`` values in their Final/diff order. Atom IDs use the first eight
+    hexadecimal characters of the atom-identity SHA-256 digest and receive
+    deterministic ``-N`` suffixes on collisions.
+    """
+
+    gap_counts: dict[tuple[str, int], int] = defaultdict(int)
+    id_counts: dict[str, int] = defaultdict(int)
+    whole_file_descriptors: dict[str, tuple[str | None, ...]] = {}
+    replay_atoms: list[ReplayAtom] = []
+
+    for hunk in hunks:
+        kind = _kind(hunk)
+        is_whole_file = kind is AtomKind.WHOLE_FILE
+        if is_whole_file:
+            descriptor = (hunk.base_mode, hunk.base_oid, hunk.final_mode, hunk.final_oid)
+            prior_descriptor = whole_file_descriptors.get(hunk.path)
+            if prior_descriptor is not None:
+                if descriptor != prior_descriptor:
+                    raise ValueError(
+                        f"whole-file hunks for {hunk.path!r} disagree on Git object metadata"
+                    )
+                continue
+            whole_file_descriptors[hunk.path] = descriptor
+
+        gap_seq = 0
+        base_start = 0 if is_whole_file else hunk.base_start
+        base_len = 0 if is_whole_file else hunk.base_len
+        final_start = 0 if is_whole_file else hunk.final_start
+        final_len = 0 if is_whole_file else hunk.final_len
+        if not is_whole_file and base_len == 0:
+            gap_key = (hunk.path, hunk.base_start)
+            gap_seq = gap_counts[gap_key]
+            gap_counts[gap_key] += 1
+
+        content_hash = _whole_file_content_hash(hunk) if is_whole_file else _text_content_hash(hunk)
+        short_id = _atom_id_digest(
+            path=hunk.path,
+            base_start=base_start,
+            base_len=base_len,
+            gap_seq=gap_seq,
+            content_hash=content_hash,
+        )[:8]
+        id_counts[short_id] += 1
+        collision_number = id_counts[short_id]
+        atom_id = short_id if collision_number == 1 else f"{short_id}-{collision_number}"
+
+        atom = Atom(
+            atom_id=atom_id,
+            path=hunk.path,
+            kind=kind,
+            base_start=base_start,
+            base_len=base_len,
+            final_start=final_start,
+            final_len=final_len,
+            gap_seq=gap_seq,
+            content_hash=content_hash,
+            owner=None,
+            state=AtomState.UNASSIGNED,
+            preview=_whole_file_preview(hunk) if is_whole_file else _preview(hunk),
+        )
+        replay_atoms.append(
+            ReplayAtom(
+                atom=atom,
+                removed_lines=(
+                    () if is_whole_file else tuple(_line_bytes(line) for line in hunk.removed_lines)
+                ),
+                added_lines=(
+                    () if is_whole_file else tuple(_line_bytes(line) for line in hunk.added_lines)
+                ),
+            )
+        )
+
+    return tuple(replay_atoms)
+
+
+def build_atoms(hunks: Sequence[RawDiffHunk]) -> tuple[Atom, ...]:
+    """Convert raw hunks to compact persistent atoms."""
+
+    return tuple(replay_atom.atom for replay_atom in atomize_hunks(hunks))