github-task-protocol 1.0.1__py3-none-any.whl

gtp/presentation.py

@@ -0,0 +1,419 @@
+"""Plain-first Japanese and machine-exact CLI projections."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .carrier import CarrierResult
+from .status import StatusResult
+
+
+AUTHORITY_NOTICE = "この出力は変更・完了・mergeの許可を与えません"
+HALT_MESSAGES = {
+    "invalid_record": "GTP Recordの形式、内容、編集状態のいずれかが不正です",
+    "conflicting_records": "同じ役割のRecordが競合しています",
+    "invalid_transition": "Recordの順序または参照関係が成立していません",
+    "invalid_binding": "Issue、branch、PR、scopeの束縛が一致しません",
+    "invalid_evidence": "Done Conditionに対応するEvidenceを確認できません",
+    "stale_evidence": "EvidenceがDoneのsource head SHAと一致しません",
+    "terminal_violation": "terminal stateの前後関係に違反するRecordまたはmergeがあります",
+}
+EVIDENCE_LIMITS = [
+    "actor本人性",
+    "credential安全性",
+    "GitHub外情報を参照しなかったこと",
+]
+
+
+def _record(value: dict[str, Any] | None) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    observation = {
+        key: value[key]
+        for key in ("url", "aliases", "comment_id")
+        if key in value
+    }
+    result = {
+        "type": value.get("type"),
+        "id": value.get("id"),
+        "observation": observation,
+    }
+    if isinstance(value.get("content"), dict):
+        result["content"] = value["content"]
+    return result
+
+
+def _content(record: dict[str, Any] | None) -> dict[str, Any]:
+    value = record.get("content") if isinstance(record, dict) else None
+    return value if isinstance(value, dict) else {}
+
+
+def _task_context(
+    *,
+    state: str | None,
+    acquisition_complete: bool,
+    contract: dict[str, Any] | None,
+    start: dict[str, Any] | None,
+    done: dict[str, Any] | None,
+    branch: dict[str, Any] | None,
+    pr: str | None,
+) -> dict[str, Any]:
+    contract_content = _content(contract)
+    start_content = _content(start)
+    done_content = _content(done)
+    done_conditions = contract_content.get("done_conditions")
+    evidence = done_content.get("evidence")
+    conditions: dict[str, dict[str, Any]] = {}
+    if isinstance(done_conditions, dict):
+        evidence_map = evidence if isinstance(evidence, dict) else {}
+        for condition_id in sorted(done_conditions):
+            condition = done_conditions[condition_id]
+            if not isinstance(condition, dict):
+                continue
+            evidence_url = evidence_map.get(condition_id)
+            conditions[condition_id] = {
+                "text": condition.get("text"),
+                "evidence_kind": condition.get("evidence_kind"),
+                "evidence_url": evidence_url if isinstance(evidence_url, str) else None,
+                "evidence_status": (
+                    "presented" if isinstance(evidence_url, str) else "not_presented"
+                ),
+            }
+
+    not_proven: list[str] = []
+    if not acquisition_complete:
+        not_proven.append("GitHub情報の取得が不完全なためtask context未確認")
+    elif not contract_content:
+        not_proven.append("Contract未確認")
+    else:
+        missing = [
+            f"{condition_id}: Evidence未提示"
+            for condition_id, condition in conditions.items()
+            if condition["evidence_status"] == "not_presented"
+        ]
+        not_proven.extend(missing)
+        if done is None:
+            not_proven.append("Done Claim未提示")
+        elif state == "in_progress":
+            not_proven.append("native merge未確認")
+        elif state == "halt" and not missing:
+            not_proven.append("protocol不適合が未解決")
+        elif state == "stopped":
+            not_proven.append("このIssueは完了を証明せず停止済み")
+
+    branch_name = branch.get("name") if isinstance(branch, dict) else None
+    if not isinstance(branch_name, str):
+        candidate = start_content.get("branch")
+        branch_name = candidate if isinstance(candidate, str) else None
+    scope = contract_content.get("scope")
+    return {
+        "goal": contract_content.get("goal"),
+        "scope": scope if isinstance(scope, list) else [],
+        "branch": branch_name,
+        "pr": pr,
+        "conditions": conditions,
+        "not_proven": not_proven,
+        "evidence_limits": list(EVIDENCE_LIMITS),
+    }
+
+
+def _branch(value: dict[str, Any] | None) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    observation = {"exists": value["exists"]} if "exists" in value else {}
+    return {"name": value.get("name"), "observation": observation}
+
+
+def _next_action(result: StatusResult) -> str:
+    if result.state is None:
+        return "retry_acquisition"
+    if result.state == "unmanaged":
+        return "post_contract"
+    if result.state == "ready":
+        return "post_start"
+    if result.state == "halt":
+        return "inspect_halt"
+    if result.state == "done":
+        return "none_done"
+    if result.state == "stopped":
+        return "none_stopped"
+    if result.current.get("done") is not None:
+        return "await_merge"
+    if result.current.get("bound_pr") or result.current.get("pr_candidates"):
+        return "post_done"
+    return "continue_work"
+
+
+def _primary_url(result: StatusResult) -> str:
+    if result.acquisition_errors:
+        resource = result.acquisition_errors[0].get("resource")
+        return resource if isinstance(resource, str) else result.issue_url
+    if result.diagnostics and result.diagnostics[0].urls:
+        return result.diagnostics[0].urls[0]
+    current = result.current
+    if isinstance(current.get("bound_pr"), str):
+        return current["bound_pr"]
+    candidates = current.get("pr_candidates")
+    if isinstance(candidates, list) and candidates and isinstance(candidates[0], str):
+        return candidates[0]
+    for kind in ("stop", "done", "start", "contract"):
+        value = current.get(kind)
+        if isinstance(value, dict) and isinstance(value.get("url"), str):
+            return value["url"]
+    return result.issue_url
+
+
+def status_projection(result: StatusResult) -> dict[str, Any]:
+    diagnostics = [item.projection() for item in result.diagnostics]
+    current = result.current
+    candidates = current.get("pr_candidates")
+    candidate = candidates[0] if isinstance(candidates, list) and len(candidates) == 1 else None
+    contract = _record(current.get("contract"))
+    start = _record(current.get("start"))
+    done = _record(current.get("done"))
+    stop = _record(current.get("stop"))
+    branch = _branch(current.get("branch"))
+    bound_pr = current.get("bound_pr")
+    done_pr = _content(done).get("pr_ref")
+    pr = (
+        bound_pr
+        if isinstance(bound_pr, str)
+        else candidate
+        if isinstance(candidate, str)
+        else done_pr
+        if isinstance(done_pr, str)
+        else None
+    )
+    return {
+        "gtp": "1.0",
+        "command": "status",
+        "issue_url": result.issue_url,
+        "state": result.state,
+        "halt_reason": diagnostics[0]["token"] if result.state == "halt" and diagnostics else None,
+        "details": [item["detail"] for item in diagnostics if "detail" in item],
+        "next_action": _next_action(result),
+        "primary_url": _primary_url(result),
+        "authority": "none",
+        "acquisition": "incomplete" if result.acquisition_errors else "complete",
+        "contract": contract,
+        "start": start,
+        "done": done,
+        "stop": stop,
+        "branch": branch,
+        "pr_candidate": candidate,
+        "bound_pr": bound_pr,
+        "diagnostics": diagnostics,
+        "acquisition_errors": result.acquisition_errors,
+        "task_context": _task_context(
+            state=result.state,
+            acquisition_complete=not result.acquisition_errors,
+            contract=contract,
+            start=start,
+            done=done,
+            branch=branch,
+            pr=pr,
+        ),
+    }
+
+
+def _plain_summary(machine: dict[str, Any], context: dict[str, Any]) -> list[str]:
+    state = machine["state"]
+    conclusion = (
+        "GitHub情報を最後まで取得できていないため、まだ判断できません。"
+        if state is None
+        else "このIssueの完了は確認できません。作業を止めて人が確認してください。"
+        if state == "halt"
+        else "このIssueの完了を確認しました。"
+        if state == "done"
+        else "このIssueは完了を主張せず終了しています。"
+        if state == "stopped"
+        else "完了条件の確認資料はそろっていますが、マージはまだです。"
+        if machine["next_action"] == "await_merge"
+        else "このIssueはまだ作業途中です。"
+    )
+    lines = ["かんたんな説明:", f"  結論: {conclusion}"]
+    if state is None:
+        lines.extend(
+            [
+                f"  次にすること: GitHub情報をもう一度取得してください。最初の確認先: {machine['primary_url']}",
+                "  大事な点: 情報を取得できないことと、記録に矛盾があることは別です。",
+                "  ここまでが人向けの説明です。続くJSONは機械処理用です。",
+            ]
+        )
+        return lines
+    if state == "halt":
+        lines.append(f"  次にすること: 原因の記録を開いてください: {machine['primary_url']}")
+
+    goal = context.get("goal")
+    if isinstance(goal, str):
+        scope = context.get("scope")
+        scope_text = "、".join(scope) if isinstance(scope, list) and scope else "記録なし"
+        lines.extend(
+            [
+                f"  この作業の目的: {goal}",
+                f"  変更してよい場所: {scope_text}",
+                f"  作業場所: branch {context.get('branch') or '未確認'}"
+                f" / PR {context.get('pr') or '未確認'}",
+            ]
+        )
+
+    conditions = context.get("conditions")
+    if not isinstance(conditions, dict) or not conditions:
+        lines.append("  ここまでが人向けの説明です。続くJSONは機械処理用です。")
+        return lines
+    presented = [
+        (condition_id, condition)
+        for condition_id, condition in conditions.items()
+        if condition.get("evidence_status") == "presented"
+    ]
+    missing = [
+        (condition_id, condition)
+        for condition_id, condition in conditions.items()
+        if condition.get("evidence_status") == "not_presented"
+    ]
+    evidence_confirmed = state == "done" or machine["next_action"] == "await_merge"
+    if presented:
+        lines.append(
+            "  確認できた完了条件:"
+            if evidence_confirmed
+            else "  記録に確認資料へのリンクがある条件（達成済みとはまだ断定しません）:"
+        )
+        for condition_id, condition in presented:
+            lines.extend(
+                [
+                    f"    - {condition.get('text') or '説明未記録'}（識別子: {condition_id}）",
+                    f"      確認資料: {condition.get('evidence_url')}",
+                ]
+            )
+    if missing:
+        lines.append("  確認資料が足りない条件:")
+        for condition_id, condition in missing:
+            lines.extend(
+                [
+                    f"    - {condition.get('text') or '説明未記録'}（識別子: {condition_id}）",
+                    "      不足しているもの: 条件を確認するための証拠リンク",
+                ]
+            )
+    if state == "halt":
+        lines.append(
+            "  大事な点: 足りない記録を推測で補わないでください。"
+            "この表示だけでは変更・完了・mergeできません。"
+        )
+    lines.append("  ここまでが人向けの説明です。続くJSONは機械処理用です。")
+    return lines
+
+
+def _status_text(machine: dict[str, Any]) -> list[str]:
+    state = machine["state"] if machine["state"] is not None else "不明"
+    action = machine["next_action"]
+    branch = machine.get("branch")
+    branch_name = branch.get("name") if isinstance(branch, dict) else None
+    stop_text = {
+        "unmanaged": "停止は不要です。Contractを記録する段階です",
+        "ready": "停止は不要です。作業開始前です",
+        "in_progress": "停止は不要です。作業中です",
+        "halt": "このtransitionは進められません",
+        "done": "停止は不要です。完了状態です",
+        "stopped": "このIssueでは作業を再開しません",
+        None: "状態を決められないため、このtransitionは進められません",
+    }[machine["state"]]
+    action_text = {
+        "post_contract": "目的・変更範囲・完了条件をContractとして記録してください",
+        "post_start": "Contractと作業branchをStartで束縛してください",
+        "continue_work": "束縛されたbranchで作業を続けてください",
+        "post_done": "完了条件を確認し、source headとEvidenceをDoneで提示してください",
+        "await_merge": "Done ClaimとEvidenceを確認し、人間のnative merge判断を待ってください",
+        "inspect_halt": "最初のURLを確認し、記録を推測で補わず人間へ戻してください",
+        "none_done": "追加のprotocol actionはありません",
+        "none_stopped": "必要なら新しいIssueでContractから開始してください",
+        "retry_acquisition": "GitHub情報を再取得してください",
+    }[action]
+    if machine["state"] is None:
+        errors = machine["acquisition_errors"]
+        code = errors[0].get("code", "acquisition_incomplete") if errors else "acquisition_incomplete"
+        reason = f"{code} — GitHub情報を完全に取得できず、stateを決定していません"
+    elif machine["state"] == "halt":
+        token = machine["halt_reason"]
+        reason = f"{token} — {HALT_MESSAGES.get(token, 'protocol上の矛盾または不適合を確認しました')}"
+    elif action == "await_merge":
+        reason = "Done Claimは確認済みですが、native mergeはまだ確認できません"
+    elif action == "post_done":
+        reason = f"Start、作業branch {branch_name or '（名前不明）'}、PR candidateを確認しました"
+    elif action == "continue_work":
+        reason = f"Startと作業branch {branch_name or '（名前不明）'}を確認しました"
+    else:
+        reason = {
+            "unmanaged": "有効なContractがありません",
+            "ready": "有効なContractがあり、Startはまだありません",
+            "done": "Done Claimのsource head、Evidence、native mergeを確認しました",
+            "stopped": "有効なStop Recordを確認しました",
+        }[machine["state"]]
+    lines = [
+        f"状態: {state}",
+        f"停止要否: {stop_text}",
+        f"次の行動: {action_text}",
+        f"理由: {reason}",
+        f"最初のURL: {machine['primary_url']}",
+        f"非許可表示: {AUTHORITY_NOTICE}",
+    ]
+    context = machine["task_context"]
+    lines.extend(_plain_summary(machine, context))
+    goal = context.get("goal")
+    if not isinstance(goal, str):
+        return lines
+    return lines
+
+
+def present_status(result: StatusResult) -> tuple[list[str], dict[str, Any]]:
+    machine = status_projection(result)
+    return _status_text(machine), machine
+
+
+def check_projection(result: CarrierResult) -> dict[str, Any]:
+    record = None
+    if result.record is not None:
+        record = {"type": result.record["type"], "id": result.record["id"]}
+    return {
+        "gtp": "1.0",
+        "command": "check",
+        "recognized": result.recognized,
+        "schema_valid": result.schema_valid,
+        "contextual_checks": "not_run",
+        "projected_state": None,
+        "record": record,
+        "errors": result.errors,
+        "authority": "none",
+    }
+
+
+def present_check(result: CarrierResult) -> tuple[list[str], dict[str, Any]]:
+    machine = check_projection(result)
+    if not result.recognized:
+        summary = "通常commentであり、GTP Carrierではありません"
+    elif result.schema_valid:
+        summary = "GTP Carrierとして認識し、offline schemaに適合しました"
+    else:
+        summary = "GTP Carrierとして認識しましたが、形式・JSON・schemaに適合しません"
+    return [
+        f"検査結果: {summary}",
+        "contextual checks: Issue上の参照関係とstateは検査していません",
+        f"非許可表示: {AUTHORITY_NOTICE}",
+    ], machine
+
+
+def present_input_error(message: str) -> tuple[list[str], dict[str, Any]]:
+    return [
+        "検査結果: 入力ファイルをUTF-8のMarkdown commentとして読めません",
+        "contextual checks: 実行していません",
+        f"非許可表示: {AUTHORITY_NOTICE}",
+    ], {
+        "gtp": "1.0",
+        "command": "check",
+        "recognized": None,
+        "schema_valid": None,
+        "contextual_checks": "not_run",
+        "projected_state": None,
+        "record": None,
+        "errors": [{"code": "input_error", "message": message}],
+        "authority": "none",
+    }

gtp/reducer.py

@@ -0,0 +1,184 @@
+"""Pure Server Order fold for GTP v1 Records."""
+
+from __future__ import annotations
+
+from .carrier import classify_carrier
+from .model import Comment, Diagnostic, FoldContext, FoldResult, IncompleteSnapshotError, RecordObservation
+from .urls import parse_github_url
+
+
+HALT_REASONS = frozenset(
+    {
+        "invalid_record",
+        "conflicting_records",
+        "invalid_transition",
+        "invalid_binding",
+        "invalid_evidence",
+        "stale_evidence",
+        "terminal_violation",
+    }
+)
+
+
+def _diagnose(result: FoldResult, token: str, *urls: str) -> None:
+    diagnostic = Diagnostic(token, tuple(dict.fromkeys(urls)))
+    if diagnostic not in result.diagnostics:
+        result.diagnostics.append(diagnostic)
+
+
+def _remove_observation(result: FoldResult, target: RecordObservation) -> None:
+    result.active[target.type] = [item for item in result.active[target.type] if item is not target]
+    if result.bound_contract is target:
+        result.bound_contract = None
+    if result.bound_start is target:
+        result.bound_start = None
+        result.started_once = False
+    if result.terminal_stop is target:
+        result.terminal_stop = None
+
+
+def _accept_context(result: FoldResult, observation: RecordObservation) -> None:
+    record_type = observation.type
+    url = observation.comment.url
+
+    if record_type == "contract":
+        result.active[record_type].append(observation)
+        if result.started_once:
+            _diagnose(result, "invalid_transition", url)
+        elif len(result.active[record_type]) > 1:
+            _diagnose(
+                result,
+                "conflicting_records",
+                *(item.comment.url for item in result.active[record_type]),
+            )
+        return
+
+    if record_type == "start":
+        result.active[record_type].append(observation)
+        if len(result.active[record_type]) > 1:
+            _diagnose(
+                result,
+                "conflicting_records",
+                *(item.comment.url for item in result.active[record_type]),
+            )
+            return
+        contracts = result.active["contract"]
+        if len(contracts) != 1:
+            _diagnose(result, "invalid_transition", url, *(item.comment.url for item in contracts))
+            return
+        contract = contracts[0]
+        if observation.record["contract_ref"] not in contract.alias_urls:
+            _diagnose(result, "invalid_binding", url, observation.record["contract_ref"])
+            return
+        result.started_once = True
+        result.bound_contract = contract
+        result.bound_start = observation
+        return
+
+    if record_type == "done":
+        result.active[record_type].append(observation)
+        if len(result.active[record_type]) > 1:
+            _diagnose(
+                result,
+                "conflicting_records",
+                *(item.comment.url for item in result.active[record_type]),
+            )
+            return
+        if not result.started_once or result.bound_contract is None:
+            _diagnose(result, "invalid_transition", url)
+            return
+        expected = result.bound_contract.record["done_conditions"]
+        actual = observation.record["evidence"]
+        if set(expected) != set(actual):
+            _diagnose(result, "invalid_evidence", url)
+            return
+        for condition_id, condition in expected.items():
+            if parse_github_url(actual[condition_id], condition["evidence_kind"]) is None:
+                _diagnose(result, "invalid_evidence", url, actual[condition_id])
+                return
+        return
+
+    if record_type == "stop":
+        result.active[record_type].append(observation)
+        result.terminal_stop = observation
+
+
+def successor_refs(comments: list[Comment]) -> list[str]:
+    refs: list[str] = []
+    for comment in comments:
+        carrier = classify_carrier(comment.body)
+        if comment.updated_at != comment.created_at or not carrier.schema_valid or carrier.record is None:
+            continue
+        record = carrier.record
+        if record["type"] == "stop" and record["reason"] == "superseded":
+            refs.append(record["successor_ref"])
+    return list(dict.fromkeys(refs))
+
+
+def fold_comments(comments: list[Comment], context: FoldContext | None = None) -> FoldResult:
+    """Fold a complete, strictly ordered issue-comment snapshot without live I/O."""
+
+    del context  # Live successor facts belong to the status adapter, not the pure fold.
+    ids = [comment.id for comment in comments]
+    if ids != sorted(ids) or len(ids) != len(set(ids)):
+        raise IncompleteSnapshotError("comment IDs must be strictly ascending and unique")
+
+    result = FoldResult()
+    for comment in comments:
+        carrier = classify_carrier(comment.body)
+        if not carrier.recognized:
+            continue
+        result.recognized_count += 1
+        result.recognized_comments.append(comment)
+
+        if comment.updated_at != comment.created_at or not carrier.schema_valid or carrier.record is None:
+            if result.terminal_stop is not None:
+                _diagnose(result, "terminal_violation", comment.url)
+            else:
+                _diagnose(result, "invalid_record", comment.url)
+            continue
+
+        observation = RecordObservation(carrier.record, comment)
+        same_id = result.ids.get(observation.id, [])
+        identical = next((item for item in same_id if item.record == observation.record), None)
+        if identical is not None:
+            identical.add_alias(comment)
+            result.observations_by_url[comment.url] = identical
+            continue
+
+        if result.terminal_stop is not None:
+            result.ids.setdefault(observation.id, []).append(observation)
+            result.observations_by_url[comment.url] = observation
+            _diagnose(result, "terminal_violation", comment.url)
+            continue
+
+        if same_id:
+            members = [url for item in same_id for url in item.alias_urls] + [comment.url]
+            for item in same_id:
+                _remove_observation(result, item)
+            result.ids[observation.id].append(observation)
+            result.observations_by_url[comment.url] = observation
+            _diagnose(result, "invalid_record", *members)
+            continue
+
+        result.ids.setdefault(observation.id, []).append(observation)
+        result.observations_by_url[comment.url] = observation
+        _accept_context(result, observation)
+
+    return result
+
+
+def historical_state(result: FoldResult) -> str:
+    if result.recognized_count == 0:
+        return "unmanaged"
+    if result.terminal_stop is not None:
+        if any(item.token == "terminal_violation" for item in result.diagnostics):
+            return "halt"
+        return "stopped"
+    if result.diagnostics:
+        return "halt"
+    if not result.started_once and len(result.active["contract"]) == 1:
+        return "ready"
+    if result.started_once:
+        return "in_progress"
+    return "halt"