shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/feedback.py

@@ -0,0 +1,180 @@
+"""The frozen PR review feedback a Leader analyses, and the rules its reports must satisfy."""
+
+from __future__ import annotations
+
+from enum import StrEnum, auto
+from typing import Annotated
+
+from pydantic import Field, StringConstraints, model_validator
+
+from shikiru.domain.reports import (
+    DECISION_ACCEPT,
+    FeedbackAction,
+    FeedbackAnalysis,
+    FeedbackVerdict,
+    Report,
+)
+from shikiru.domain.tasks import DomainModel
+
+_Text = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+
+
+class FeedbackContractError(ValueError):
+    """A feedback report does not account for its snapshot or cannot be acted on."""
+
+
+class FeedbackSourceKind(StrEnum):
+    """Where a source item of feedback was written."""
+
+    REVIEW_BODY = auto()
+    DISCUSSION = auto()
+
+
+class FeedbackStep(StrEnum):
+    """What the engine may do next with a checked analysis."""
+
+    ESCALATE = auto()
+    IMPLEMENT = auto()
+    VERIFY = auto()
+
+
+class FeedbackMessage(DomainModel):
+    """One comment of a source item, in the order it was written.
+
+    `new` marks a comment this round must answer; the others were handled by earlier rounds
+    or are our own replies.
+    """
+
+    author: str | None
+    body: str
+    url: str
+    new: bool = False
+
+
+class FeedbackSource(DomainModel):
+    """A review body or an original inline discussion, with the replies that followed it."""
+
+    id: _Text
+    kind: FeedbackSourceKind
+    url: str
+    location: str = ""
+    outdated: bool = False
+    resolved: bool = False
+    messages: list[FeedbackMessage] = Field(min_length=1)
+
+
+class FeedbackSnapshot(DomainModel):
+    """The feedback of one round, fixed when the round starts."""
+
+    pull_request_url: str
+    head_sha: str
+    sources: list[FeedbackSource] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def _source_ids_are_unique(self) -> FeedbackSnapshot:
+        ids = self.source_ids
+        if len(set(ids)) != len(ids):
+            message = "sources: duplicate ids"
+            raise ValueError(message)
+        return self
+
+    @property
+    def source_ids(self) -> list[str]:
+        """The identities of the sources, in snapshot order."""
+        return [source.id for source in self.sources]
+
+    def only(self, source_ids: set[str]) -> FeedbackSnapshot:
+        """Return the snapshot restricted to `source_ids`."""
+        return self.model_copy(
+            update={"sources": [source for source in self.sources if source.id in source_ids]}
+        )
+
+
+class FeedbackInput(DomainModel):
+    """What a feedback turn is given: snapshot, analysis once made, round limit, tip verified."""
+
+    snapshot: FeedbackSnapshot
+    analysis: FeedbackAnalysis | None = None
+    final_round: bool = False
+    tip: str | None = None
+
+
+def check_analysis(snapshot: FeedbackSnapshot, analysis: FeedbackAnalysis) -> None:
+    """Require one decision for each source of `snapshot` and no other."""
+    expected = set(snapshot.source_ids)
+    decided = {decision.source_id for decision in analysis.decisions}
+    unknown = decided - expected
+    if unknown:
+        message = f"decisions name unknown source ids {sorted(unknown)}"
+        raise FeedbackContractError(message)
+    missing = expected - decided
+    if missing:
+        message = f"decisions leave source ids {sorted(missing)} without a decision"
+        raise FeedbackContractError(message)
+
+
+def next_feedback_step(analysis: FeedbackAnalysis) -> FeedbackStep:
+    """Choose the step after `analysis`: an Operator question first, then work, then replies.
+
+    A decision that needs the Operator is never read as approval to carry out the work of
+    the others, and a round with no accepted work needs no Implementer turn.
+    """
+    if operator_questions(analysis):
+        return FeedbackStep.ESCALATE
+    if analysis.work:
+        return FeedbackStep.IMPLEMENT
+    return FeedbackStep.VERIFY
+
+
+def operator_questions(analysis: FeedbackAnalysis) -> list[tuple[str, str]]:
+    """Return each (source id, question) the Operator must answer."""
+    return [
+        (decision.source_id, decision.detail)
+        for decision in analysis.decisions
+        if decision.action is FeedbackAction.NEEDS_OPERATOR
+    ]
+
+
+def check_verdict(
+    snapshot: FeedbackSnapshot, analysis: FeedbackAnalysis, verdict: FeedbackVerdict
+) -> None:
+    """Require an accepting verdict to verify exactly the replies the analysis drafted."""
+    check_analysis(snapshot, analysis)
+    if verdict.decision != DECISION_ACCEPT:
+        return
+    if operator_questions(analysis):
+        message = "decision: 'accept' is not available while a decision needs the Operator"
+        raise FeedbackContractError(message)
+    expected = {
+        decision.source_id
+        for decision in analysis.decisions
+        if decision.action is not FeedbackAction.NEEDS_OPERATOR
+    }
+    verified = {reply.source_id for reply in verdict.replies}
+    if verified != expected:
+        message = (
+            f"replies must cover exactly source ids {sorted(expected)}, got {sorted(verified)}"
+        )
+        raise FeedbackContractError(message)
+
+
+def check_feedback_report(feedback: FeedbackInput, report: Report) -> None:
+    """Check `report` against the frozen `feedback` its turn was given."""
+    if isinstance(report, FeedbackAnalysis):
+        check_analysis(feedback.snapshot, report)
+    elif isinstance(report, FeedbackVerdict):
+        if feedback.analysis is None:
+            message = "a feedback verdict needs the analysis it verifies"
+            raise FeedbackContractError(message)
+        check_verdict(feedback.snapshot, feedback.analysis, report)
+
+
+def publishable_replies(
+    snapshot: FeedbackSnapshot, analysis: FeedbackAnalysis, verdict: FeedbackVerdict
+) -> dict[str, str]:
+    """Return the verified reply of each source, or fail when the round is not accepted."""
+    if verdict.decision != DECISION_ACCEPT:
+        message = f"a '{verdict.decision}' verdict leaves no reply publishable"
+        raise FeedbackContractError(message)
+    check_verdict(snapshot, analysis, verdict)
+    return {reply.source_id: reply.reply for reply in verdict.replies}

shikiru/domain/feedback_rounds.py

@@ -0,0 +1,172 @@
+"""The durable progress of one PR feedback round and the pure rules that move it."""
+
+from __future__ import annotations
+
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING
+
+from pydantic import Field
+
+from shikiru.domain.feedback import FeedbackSnapshot, FeedbackSourceKind
+from shikiru.domain.reports import FeedbackAction, FeedbackAnalysis
+from shikiru.domain.tasks import DomainModel
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from shikiru.domain.reports import TestRun
+
+MARKER_PREFIX = "shikiru-feedback"
+MARKER_SEPARATOR = ":"
+REPLY_SEPARATOR = "\n\n"
+REVIEW_LINK_PREFIX = "In reply to"
+FIXED_PREFIX = "Fixed in"
+CHECKS_PREFIX = "Verified by"
+CHECKS_SEPARATOR = "; "
+SHORT_SHA_LENGTH = 12
+
+
+class FeedbackStage(StrEnum):
+    """Where a feedback round stands; the first five stages are the unfinished ones."""
+
+    ANALYSIS = auto()
+    IMPLEMENTATION = auto()
+    VERIFICATION = auto()
+    PUBLICATION = auto()
+    REPLIES = auto()
+    HANDLED = auto()
+    ABANDONED = auto()
+
+
+UNFINISHED_STAGES = frozenset(
+    (
+        FeedbackStage.ANALYSIS,
+        FeedbackStage.IMPLEMENTATION,
+        FeedbackStage.VERIFICATION,
+        FeedbackStage.PUBLICATION,
+        FeedbackStage.REPLIES,
+    )
+)
+
+
+class ReplyState(StrEnum):
+    """How far one reply got: stored, possibly sent (its outcome unknown), or confirmed sent."""
+
+    PLANNED = auto()
+    SENDING = auto()
+    SENT = auto()
+
+
+class PublicationAction(StrEnum):
+    """What to do with the verified tip given where the remote branch is."""
+
+    PUSH = auto()
+    ALREADY_PUBLISHED = auto()
+    REMOTE_MOVED = auto()
+
+
+class Alignment(StrEnum):
+    """How the task branch relates to the remote branch before a round edits it."""
+
+    ALIGNED = auto()
+    FAST_FORWARD = auto()
+    DIVERGED = auto()
+
+
+class FeedbackRound(DomainModel):
+    """One batch of review feedback and everything done about it so far."""
+
+    id: int
+    task_id: str
+    pull_request_url: str
+    review_ids: list[str]
+    comment_ids: list[str] = Field(default_factory=list)
+    snapshot: FeedbackSnapshot
+    stage: FeedbackStage
+    analysis: FeedbackAnalysis | None = None
+    attempts: int = 0
+    blocked: bool = False
+    expected_remote_sha: str
+    verified_sha: str | None = None
+    published_sha: str | None = None
+    checks: str = ""
+    verified_replies: dict[str, str] = Field(default_factory=dict)
+
+
+class FeedbackReply(DomainModel):
+    """The immutable reply to one source item, with the marker that finds it again."""
+
+    round_id: int
+    source_id: str
+    kind: FeedbackSourceKind
+    marker: str
+    body: str
+    state: ReplyState = ReplyState.PLANNED
+    posted_url: str | None = None
+
+
+def reply_marker(task_id: str, round_id: int, source_id: str) -> str:
+    """Return the stable marker that identifies the reply to `source_id` in `round_id`."""
+    parts = (MARKER_PREFIX, task_id, str(round_id), source_id)
+    return f"<!-- {MARKER_SEPARATOR.join(parts)} -->"
+
+
+def is_own_reply(body: str) -> bool:
+    """Return whether a comment `body` carries the marker of a reply this engine posted."""
+    return MARKER_PREFIX in body
+
+
+def reply_body(
+    *,
+    reply: str,
+    marker: str,
+    review_url: str | None,
+    fixed_sha: str | None,
+    checks: str,
+) -> str:
+    """Compose a reply: the link of a review-body source, the verified text, the fix, the marker."""
+    parts: list[str] = []
+    if review_url is not None:
+        parts.append(f"{REVIEW_LINK_PREFIX} {review_url}")
+    parts.append(reply.strip())
+    if fixed_sha is not None:
+        fixed = f"{FIXED_PREFIX} {fixed_sha[:SHORT_SHA_LENGTH]}."
+        parts.append(f"{fixed} {CHECKS_PREFIX} {checks}." if checks else fixed)
+    parts.append(marker)
+    return REPLY_SEPARATOR.join(parts)
+
+
+def describe_checks(tests: Sequence[TestRun]) -> str:
+    """Name the checks an Implementer ran and how each ended."""
+    return CHECKS_SEPARATOR.join(f"{test.name} {test.result}" for test in tests)
+
+
+def fixed_source_ids(analysis: FeedbackAnalysis) -> set[str]:
+    """Return the sources whose decision changed code."""
+    return {
+        decision.source_id
+        for decision in analysis.decisions
+        if decision.action is FeedbackAction.ADDRESS
+    }
+
+
+def plan_publication(*, expected: str, remote_head: str, local_tip: str) -> PublicationAction:
+    """Decide how to publish `local_tip` when the remote branch is at `remote_head`.
+
+    The remote only ever matches what the round captured (`expected`) or the tip itself; any
+    other head is somebody else's work that a push must not overwrite.
+    """
+    if remote_head == local_tip:
+        return PublicationAction.ALREADY_PUBLISHED
+    if remote_head != expected:
+        return PublicationAction.REMOTE_MOVED
+    return PublicationAction.PUSH
+
+
+def align_with_remote(*, remote_in_local: bool, local_in_remote: bool) -> Alignment:
+    """Relate the task branch to the remote branch from their ancestry."""
+    if remote_in_local:
+        return Alignment.ALIGNED
+    if local_in_remote:
+        return Alignment.FAST_FORWARD
+    return Alignment.DIVERGED

shikiru/domain/fencing.py

@@ -0,0 +1,31 @@
+"""Markdown code fencing that survives backticks already present in its content."""
+
+from __future__ import annotations
+
+_BACKTICK = "`"
+_MIN_FENCE_LENGTH = 3
+
+
+def fence(content: str, info: str = "") -> str:
+    """Wrap `content` in a backtick fence longer than any backtick run already inside it.
+
+    `info` is the fence's info string (e.g. `text` or `json`). Quoting untrusted content
+    (an agent's report, a request or a pane screen) this way keeps a `` ``` `` or `` ```` ``
+    the content already contains from closing the fence early and turning the rest of it
+    into instructions the agent reads as ours.
+    """
+    length = max(_MIN_FENCE_LENGTH, _longest_backtick_run(content) + 1)
+    marker = _BACKTICK * length
+    return f"{marker}{info}\n{content}\n{marker}"
+
+
+def _longest_backtick_run(content: str) -> int:
+    longest = 0
+    current = 0
+    for character in content:
+        if character == _BACKTICK:
+            current += 1
+            longest = max(longest, current)
+        else:
+            current = 0
+    return longest

shikiru/domain/ladder.py

@@ -0,0 +1,102 @@
+"""Rung selection, move-up rules and counter resets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from shikiru.domain.tasks import DEFAULT_COMPLEXITY, Counters, Role, Task
+
+if TYPE_CHECKING:
+    from shikiru.agents.contracts import Rung
+    from shikiru.config.settings import Settings
+
+REJECTIONS_FIELD = "rejections_on_rung"
+
+
+def _ladder_for(role: Role, task: Task, settings: Settings) -> list[Rung]:
+    if role is Role.LEADER:
+        return settings.roles.leader.ladder
+    if role is Role.IMPLEMENTER:
+        return settings.roles.implementer.ladder_for(task.complexity or DEFAULT_COMPLEXITY)
+    return settings.roles.helper.ladder
+
+
+def pick_rung(task: Task, role: Role, settings: Settings) -> Rung:
+    """Resolve `role`'s rung: the operator override, else the ladder at `rung_index[role]`."""
+    override = task.overrides.get(role)
+    if override is not None:
+        return override
+    ladder = _ladder_for(role, task, settings)
+    return ladder[task.rung_index.get(role, 0)]
+
+
+def reset_for_rung_change(counters: Counters) -> Counters:
+    """`rejections_on_rung` resets whenever the Implementer's rung changes."""
+    return counters.model_copy(update={REJECTIONS_FIELD: 0})
+
+
+def reset_for_new_iteration(counters: Counters) -> Counters:
+    """`consults` resets at the start of every implement/verify iteration."""
+    return counters.model_copy(update={"consults": 0})
+
+
+def reset_for_integration_attempt(counters: Counters) -> Counters:
+    """`conflict_rounds` resets at the start of every integration attempt."""
+    return counters.model_copy(update={"conflict_rounds": 0})
+
+
+@dataclass(frozen=True)
+class RungMove:
+    """The new `rung_index`, the override to clear and `counters` after moving a role up."""
+
+    rung_index: dict[Role, int]
+    cleared_overrides: dict[Role, Rung]
+    counters: Counters
+
+
+def move_up(
+    task: Task,
+    role: Role,
+    settings: Settings,
+    *,
+    different_agent: bool = False,
+    blocked_agents: frozenset[str] = frozenset(),
+) -> RungMove | None:
+    """Advance `role` one rung up its ladder from the rung currently resolved by `pick_rung`.
+
+    Comparing against the resolved rung, not `ladder[rung_index]`, matters because that rung may
+    be an operator override; `different_agent=True` then skips ladder rungs on that override's
+    agent too. Moving up clears `role`'s override as observed in `task`: an automatic move replaces
+    a manual pin, since keeping it would make the move a no-op and could loop recovery on a
+    blocked agent. The store clears it only while it still equals that observed rung, so a pin the
+    operator set since survives.
+    For the Implementer, `rejections_on_rung` also resets, since it counts rework at one rung.
+    Agents in `blocked_agents` are skipped when selecting the destination rung.
+
+    With `different_agent=True` the move is a quota fallback: rungs above the current one come
+    first, then the rungs from the bottom of the ladder up, so a role parked on the last rung can
+    return to an earlier agent that is no longer blocked.
+
+    Returns `None` once no rung satisfies the constraints; the caller then keeps the task on its
+    current rung.
+    """
+    ladder = _ladder_for(role, task, settings)
+    current_rung = pick_rung(task, role, settings)
+    current_index = task.rung_index.get(role, 0)
+    above = range(current_index + 1, len(ladder))
+    below = range(current_index + 1) if different_agent else range(0)
+    for index in (*above, *below):
+        candidate = ladder[index]
+        if candidate.agent in blocked_agents:
+            continue
+        if different_agent and candidate.agent == current_rung.agent:
+            continue
+        rung_index = dict(task.rung_index)
+        rung_index[role] = index
+        cleared = {role: task.overrides[role]} if role in task.overrides else {}
+        counters = (
+            reset_for_rung_change(task.counters) if role is Role.IMPLEMENTER else task.counters
+        )
+        return RungMove(rung_index=rung_index, cleared_overrides=cleared, counters=counters)
+    return None

shikiru/domain/ladder_text.py

@@ -0,0 +1,44 @@
+"""Pure parsing for the initializer's comma-separated ladder field."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from shikiru.agents.contracts import Rung
+
+ENTRY_SEPARATOR = ","
+PART_SEPARATOR = ":"
+REQUIRED_PART_COUNT = 2
+OPTIONAL_EFFORT_PART_COUNT = 3
+
+
+@dataclass(frozen=True, slots=True)
+class LadderTextError(ValueError):
+    """One malformed entry in an edited ladder field."""
+
+    entry_index: int
+    detail: str
+
+    def __str__(self) -> str:
+        return self.detail
+
+
+def parse_ladder_text(value: str) -> tuple[Rung, ...]:
+    """Parse ordered `agent:model[:effort]` entries without changing the source text."""
+    if not value.strip():
+        return ()
+
+    rungs: list[Rung] = []
+    for index, raw_entry in enumerate(value.split(ENTRY_SEPARATOR)):
+        entry = raw_entry.strip()
+        parts = tuple(part.strip() for part in entry.split(PART_SEPARATOR))
+        if len(parts) not in {REQUIRED_PART_COUNT, OPTIONAL_EFFORT_PART_COUNT}:
+            detail = "use agent:model or agent:model:effort"
+            raise LadderTextError(index, detail)
+        if any(not part for part in parts):
+            detail = "each agent, model and effort value must be non-empty"
+            raise LadderTextError(index, detail)
+        agent, model = parts[:REQUIRED_PART_COUNT]
+        effort = parts[-1] if len(parts) == OPTIONAL_EFFORT_PART_COUNT else None
+        rungs.append(Rung(agent=agent, model=model, effort=effort))
+    return tuple(rungs)

shikiru/domain/levels.py

@@ -0,0 +1,44 @@
+"""Usage levels: how full a share of a limit is against its warn and alert thresholds."""
+
+from __future__ import annotations
+
+from enum import StrEnum, auto
+
+WHOLE_PERCENT = 100
+
+
+class UsageLevel(StrEnum):
+    """Whether a used share is below the warn threshold, from it, or from the alert threshold."""
+
+    OK = auto()
+    WARN = auto()
+    ALERT = auto()
+
+
+def displayed_pct(used_pct: float) -> int:
+    """Return the whole percentage a surface shows for a used share (`41.6` shows `42`)."""
+    return round(used_pct)
+
+
+def usage_level(used_pct: float, *, warn_pct: int, alert_pct: int) -> UsageLevel:
+    """Classify `used_pct` by the whole percentage shown: `alert_pct` and above is ALERT."""
+    shown = displayed_pct(used_pct)
+    if shown >= alert_pct:
+        return UsageLevel.ALERT
+    if shown >= warn_pct:
+        return UsageLevel.WARN
+    return UsageLevel.OK
+
+
+def free_space_level(
+    free_bytes: int, total_bytes: int, *, warn_pct: int, alert_pct: int
+) -> UsageLevel:
+    """Classify free space below `alert_pct` percent as ALERT and below `warn_pct` as WARN.
+
+    The share is compared as exact byte counts, so it is never rounded into a level.
+    """
+    if free_bytes * WHOLE_PERCENT < alert_pct * total_bytes:
+        return UsageLevel.ALERT
+    if free_bytes * WHOLE_PERCENT < warn_pct * total_bytes:
+        return UsageLevel.WARN
+    return UsageLevel.OK