patchrail 0.1.0__py3-none-any.whl

patchrail/reviewer_quick_check.py

@@ -0,0 +1,650 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+REVIEWER_PACKET_SCHEMA_VERSION = "patchrail.reviewer_quick_check_artifacts.v1"
+REVIEWER_PACKET_GENERATED_FROM = "local_checkout"
+
+
+def _run_patchrail(
+    args: list[str], *, root: Path, allow_nonzero: bool = False
+) -> subprocess.CompletedProcess[str]:
+    proc = subprocess.run(
+        [sys.executable, "-m", "patchrail", *args],
+        cwd=root,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if proc.returncode != 0 and not allow_nonzero:
+        sys.stderr.write(proc.stderr)
+        raise SystemExit(proc.returncode)
+    return proc
+
+
+def _fenced(label: str, text: str) -> str:
+    cleaned = text.strip()
+    return f"```{label}\n{cleaned}\n```"
+
+
+def _display_path(path: Path, *, root: Path) -> str:
+    if not path.is_absolute():
+        return path.as_posix()
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return path.name
+
+
+def _release_readiness_markdown(payload: dict[str, object]) -> str:
+    checks = payload["checks"]
+    safety = payload["safety"]
+    if not isinstance(checks, dict) or not isinstance(safety, dict):
+        raise ValueError("release readiness payload must include checks and safety objects")
+
+    lines = [
+        "# PatchRail Release Readiness",
+        "",
+        f"- Schema: `{payload['schema_version']}`",
+        f"- Version: `{payload['version']}`",
+        f"- Published to PyPI: `{payload['published']}`",
+        f"- Build: `{checks['build']}`",
+        f"- Twine check: `{checks['twine_check']}`",
+        f"- Wheel smoke: `{checks['wheel_smoke']}`",
+        f"- Doctor status: `{checks['doctor_status']}`",
+        f"- Fixture smoke class: `{checks['fixture_failure_class']}`",
+        "",
+        "## Artifacts",
+        "",
+    ]
+    artifacts = payload["artifacts"]
+    if not isinstance(artifacts, list):
+        raise ValueError("release readiness payload must include an artifacts list")
+    for artifact in artifacts:
+        if not isinstance(artifact, dict):
+            raise ValueError("release readiness artifacts must be objects")
+        lines.append(
+            f"- `{artifact['file']}`: sha256 `{artifact['sha256']}`, {artifact['size_bytes']} bytes"
+        )
+
+    lines.extend(
+        [
+            "",
+            "## Safety",
+            "",
+            f"- Local-first: `{safety['local_first']}`",
+            f"- Created release tag: `{safety['created_release_tag']}`",
+            f"- Announced publicly: `{safety['announced_publicly']}`",
+            f"- Contacted third parties: `{safety['contacted_third_parties']}`",
+            f"- GitHub write permission required: `{safety['github_write_permission_required']}`",
+            f"- External model required: `{safety['external_model_required']}`",
+            "",
+            "## Manual Gates Remaining",
+            "",
+        ]
+    )
+    gates = payload["manual_gates_remaining"]
+    if not isinstance(gates, list):
+        raise ValueError("release readiness payload must include manual gates")
+    lines.extend(f"- {gate}" for gate in gates)
+    return "\n".join(lines) + "\n"
+
+
+def _write_artifacts(
+    out_dir: Path,
+    *,
+    ci_report: str,
+    release_readiness_text: str,
+    release_readiness_json: str,
+    control_plane_text: str,
+    control_plane_json: str,
+    http_api_text: str,
+    http_api_json: str,
+    gate_text: str,
+    dossier_text: str,
+    dossier_json: str,
+    dossier_schema: str,
+    reviewer_packet_schema: str,
+) -> list[str]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    artifacts = {
+        "README.md": _reviewer_packet_readme(),
+        "ci-triage-demo.md": ci_report,
+        "release-readiness.md": release_readiness_text,
+        "release-readiness.json": release_readiness_json,
+        "control-plane-evidence.md": control_plane_text,
+        "control-plane-evidence.json": control_plane_json,
+        "http-api-evidence.md": http_api_text,
+        "http-api-evidence.json": http_api_json,
+        "application-gate.txt": gate_text,
+        "application-dossier.txt": dossier_text,
+        "application-dossier.json": dossier_json,
+        "application-dossier.schema.json": dossier_schema,
+        "reviewer-quick-check-artifacts.schema.json": reviewer_packet_schema,
+    }
+    for name, content in artifacts.items():
+        (out_dir / name).write_text(content.strip() + "\n", encoding="utf-8")
+    return sorted(artifacts)
+
+
+def _artifact_detail(path: Path) -> dict[str, object]:
+    data = path.read_bytes()
+    return {
+        "path": path.name,
+        "size_bytes": len(data),
+        "sha256": hashlib.sha256(data).hexdigest(),
+    }
+
+
+def _artifact_purpose(name: str) -> str:
+    purposes = {
+        "README.md": "review order, integrity command, and safety boundary",
+        "reviewer-quick-check.md": "single-file walkthrough of local reviewer evidence",
+        "ci-triage-demo.md": "real CI Janitor output for the bundled fixture",
+        "release-readiness.md": "human-readable local build and publish-gate evidence",
+        "release-readiness.json": "structured local build and publish-gate evidence",
+        "control-plane-evidence.md": "human-readable Agent Control Plane handoff evidence",
+        "control-plane-evidence.json": "structured Agent Control Plane handoff evidence",
+        "http-api-evidence.md": "human-readable loopback HTTP API smoke evidence",
+        "http-api-evidence.json": "structured loopback HTTP API smoke evidence",
+        "application-gate.txt": "fail-closed application readiness gate output",
+        "application-dossier.txt": "human-readable draft-only application dossier",
+        "application-dossier.json": "structured draft-only application dossier",
+        "application-dossier.schema.json": "schema for the draft-only application dossier",
+        "reviewer-quick-check-artifacts.schema.json": "schema for this reviewer packet manifest",
+    }
+    return purposes.get(name, "reviewer packet artifact")
+
+
+def _write_artifact_index(out_dir: Path, artifact_names: list[str]) -> None:
+    details = [_artifact_detail(out_dir / name) for name in artifact_names]
+    lines = [
+        "# PatchRail Reviewer Packet Artifact Index",
+        "",
+        "This index lists the reviewer-facing packet artifacts in the suggested",
+        "inspection order. It is generated locally and does not perform network,",
+        "write, publish, pull request, comment, funded-issue, or application-submit",
+        "actions.",
+        "",
+        "## Artifacts",
+        "",
+        "| Artifact | Purpose | Size | SHA-256 |",
+        "| --- | --- | ---: | --- |",
+    ]
+    for detail in details:
+        path = str(detail["path"])
+        lines.append(
+            f"| `{path}` | {_artifact_purpose(path)} | {detail['size_bytes']} | "
+            f"`{detail['sha256']}` |"
+        )
+    lines.extend(
+        [
+            "",
+            "## Safety Boundary",
+            "",
+            "- Network required: `False`",
+            "- Write action required: `False`",
+            "- Application form submission performed: `False`",
+            "- PyPI publish performed: `False`",
+            "- Third-party pull request, issue comment, or funded-issue claim performed: `False`",
+            "",
+            "`manifest.json` includes this index's own byte size and SHA-256 digest for",
+            "offline integrity verification.",
+        ]
+    )
+    (out_dir / "artifact-index.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def _write_manifest(out_dir: Path, artifact_names: list[str]) -> None:
+    manifest = {
+        "schema_version": REVIEWER_PACKET_SCHEMA_VERSION,
+        "generated_from": REVIEWER_PACKET_GENERATED_FROM,
+        "network_required": False,
+        "write_action_required": False,
+        "application_form_submission_performed": False,
+        "artifacts": artifact_names,
+        "artifact_details": [_artifact_detail(out_dir / name) for name in artifact_names],
+    }
+    (out_dir / "manifest.json").write_text(
+        json.dumps(manifest, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _packet_display_path(packet_dir: Path) -> str:
+    if packet_dir.is_absolute():
+        return packet_dir.name
+    return packet_dir.as_posix()
+
+
+def _failed_integrity_payload(
+    packet_dir: Path,
+    *,
+    errors: list[str],
+    manifest_readable: bool,
+) -> dict[str, object]:
+    return {
+        "schema_version": "patchrail.reviewer_packet_integrity.v1",
+        "packet_dir": _packet_display_path(packet_dir),
+        "status": "failed",
+        "errors": errors,
+        "counts": {"artifact_count": 0, "detail_count": 0, "verified_artifact_count": 0},
+        "checks": {
+            "manifest_readable": manifest_readable,
+            "schema_version_expected": False,
+            "generated_from_expected": False,
+            "artifacts_match_details": False,
+            "regular_artifact_files": False,
+            "all_hashes_match": False,
+            "all_sizes_match": False,
+            "no_extra_files": False,
+            "safety_flags_pass": False,
+        },
+        "missing_artifacts": [],
+        "extra_files": [],
+        "mismatches": [],
+        "verified_artifacts": [],
+    }
+
+
+def verify_reviewer_packet(packet_dir: Path) -> dict[str, object]:
+    manifest_path = packet_dir / "manifest.json"
+    errors: list[str] = []
+    mismatches: list[dict[str, object]] = []
+    verified_artifacts: list[dict[str, object]] = []
+
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return _failed_integrity_payload(
+            packet_dir, errors=["missing manifest.json"], manifest_readable=False
+        )
+    except json.JSONDecodeError as exc:
+        return _failed_integrity_payload(
+            packet_dir, errors=[f"invalid manifest.json: {exc.msg}"], manifest_readable=False
+        )
+
+    if not isinstance(manifest, dict):
+        errors.append("manifest must be a JSON object")
+        manifest = {}
+
+    schema_version_expected = manifest.get("schema_version") == REVIEWER_PACKET_SCHEMA_VERSION
+    generated_from_expected = manifest.get("generated_from") == REVIEWER_PACKET_GENERATED_FROM
+    if not schema_version_expected:
+        errors.append(
+            "manifest schema_version must be "
+            f"{REVIEWER_PACKET_SCHEMA_VERSION}: {manifest.get('schema_version')}"
+        )
+    if not generated_from_expected:
+        errors.append(
+            "manifest generated_from must be "
+            f"{REVIEWER_PACKET_GENERATED_FROM}: {manifest.get('generated_from')}"
+        )
+
+    artifacts = manifest.get("artifacts")
+    artifact_details = manifest.get("artifact_details")
+    if not isinstance(artifacts, list) or not all(isinstance(item, str) for item in artifacts):
+        errors.append("manifest artifacts must be a list of file names")
+        artifacts = []
+    if not isinstance(artifact_details, list) or not all(
+        isinstance(item, dict) for item in artifact_details
+    ):
+        errors.append("manifest artifact_details must be a list of objects")
+        artifact_details = []
+
+    details_by_path: dict[str, dict[str, object]] = {}
+    duplicate_details: list[str] = []
+    for detail in artifact_details:
+        path = detail.get("path")
+        if not isinstance(path, str):
+            errors.append("artifact detail path must be a string")
+            continue
+        if Path(path).is_absolute() or "/" in path or "\\" in path:
+            errors.append(f"artifact detail path must be a local file name: {path}")
+            continue
+        if path in details_by_path:
+            duplicate_details.append(path)
+            continue
+        details_by_path[path] = detail
+
+    for path in duplicate_details:
+        errors.append(f"duplicate artifact detail: {path}")
+
+    manifest_artifacts = list(artifacts)
+    detail_paths = list(details_by_path)
+    missing_details = sorted(set(manifest_artifacts) - set(detail_paths))
+    extra_details = sorted(set(detail_paths) - set(manifest_artifacts))
+    for path in missing_details:
+        errors.append(f"artifact missing detail: {path}")
+    for path in extra_details:
+        errors.append(f"artifact detail not listed in artifacts: {path}")
+
+    missing_artifacts: list[str] = []
+    hash_mismatch = False
+    size_mismatch = False
+    regular_artifact_files = True
+    for artifact in manifest_artifacts:
+        if Path(artifact).is_absolute() or "/" in artifact or "\\" in artifact:
+            errors.append(f"artifact path must be a local file name: {artifact}")
+            continue
+        artifact_path = packet_dir / artifact
+        detail = details_by_path.get(artifact)
+        if not artifact_path.exists():
+            missing_artifacts.append(artifact)
+            continue
+        if artifact_path.is_symlink():
+            regular_artifact_files = False
+            errors.append(f"artifact must not be a symlink: {artifact}")
+            continue
+        if not artifact_path.is_file():
+            regular_artifact_files = False
+            errors.append(f"artifact must be a regular file: {artifact}")
+            continue
+        actual = _artifact_detail(artifact_path)
+        if detail is None:
+            continue
+        expected_size = detail.get("size_bytes")
+        expected_sha = detail.get("sha256")
+        actual_size = actual["size_bytes"]
+        actual_sha = actual["sha256"]
+        item_mismatches: dict[str, object] = {"path": artifact}
+        if expected_size != actual_size:
+            size_mismatch = True
+            item_mismatches["expected_size_bytes"] = expected_size
+            item_mismatches["actual_size_bytes"] = actual_size
+        if expected_sha != actual_sha:
+            hash_mismatch = True
+            item_mismatches["expected_sha256"] = expected_sha
+            item_mismatches["actual_sha256"] = actual_sha
+        if len(item_mismatches) > 1:
+            mismatches.append(item_mismatches)
+        else:
+            verified_artifacts.append(actual)
+
+    extra_files = sorted(
+        path.name
+        for path in packet_dir.iterdir()
+        if path.name != "manifest.json" and path.name not in manifest_artifacts
+    )
+    safety_flags_pass = (
+        manifest.get("network_required") is False
+        and manifest.get("write_action_required") is False
+        and manifest.get("application_form_submission_performed") is False
+    )
+    if not safety_flags_pass:
+        errors.append("manifest safety flags must all be false")
+
+    checks = {
+        "manifest_readable": True,
+        "schema_version_expected": schema_version_expected,
+        "generated_from_expected": generated_from_expected,
+        "artifacts_match_details": not missing_details and not extra_details,
+        "regular_artifact_files": regular_artifact_files and not missing_artifacts,
+        "all_hashes_match": not hash_mismatch and not missing_artifacts,
+        "all_sizes_match": not size_mismatch and not missing_artifacts,
+        "no_extra_files": not extra_files,
+        "safety_flags_pass": safety_flags_pass,
+    }
+    status = (
+        "verified"
+        if not errors
+        and not missing_artifacts
+        and not extra_files
+        and not mismatches
+        and all(checks.values())
+        else "failed"
+    )
+    return {
+        "schema_version": "patchrail.reviewer_packet_integrity.v1",
+        "packet_dir": _packet_display_path(packet_dir),
+        "status": status,
+        "manifest_schema_version": manifest.get("schema_version"),
+        "counts": {
+            "artifact_count": len(manifest_artifacts),
+            "detail_count": len(details_by_path),
+            "verified_artifact_count": len(verified_artifacts),
+        },
+        "checks": checks,
+        "errors": errors,
+        "missing_artifacts": missing_artifacts,
+        "extra_files": extra_files,
+        "mismatches": mismatches,
+        "verified_artifacts": verified_artifacts,
+    }
+
+
+def _reviewer_packet_readme() -> str:
+    return """
+# PatchRail Reviewer Packet
+
+This directory is a local, reviewer-facing evidence bundle generated from a
+checked-out PatchRail source tree.
+
+## Review Order
+
+1. `reviewer-quick-check.md` - human-readable walkthrough of the local smoke
+   test, CI triage demo, Agent Control Plane evidence, fail-closed application
+   gate, and application dossier contract.
+2. `ci-triage-demo.md` - real local CI Janitor output for the bundled fixture.
+3. `release-readiness.md` and `release-readiness.json` - local build,
+   `twine check`, wheel smoke, and manual publish gates. They do not publish to
+   PyPI or create a release tag.
+4. `control-plane-evidence.md` and `control-plane-evidence.json` - local queue
+   handoff evidence with human gates complete and execution disabled.
+5. `http-api-evidence.md` and `http-api-evidence.json` - ephemeral
+   `127.0.0.1` HTTP API smoke evidence with endpoints and human gates checked.
+6. `application-gate.txt` - expected fail-closed result until public evidence
+   is real.
+7. `application-dossier.txt` and `application-dossier.json` - local draft
+   dossier; it does not submit any external form.
+8. `manifest.json` plus the schema files - offline validation contract.
+
+## Integrity Check
+
+After copying or downloading this directory, verify it before review:
+
+```bash
+patchrail evidence verify-reviewer-packet patchrail-reviewer-packet --format markdown
+```
+
+The verifier recomputes every listed artifact's byte size and SHA-256 digest,
+rejects symlinked or non-file artifacts, rejects extra files, and exits
+non-zero if the packet has been tampered with or drifted from its manifest.
+
+## Safety Boundary
+
+- Network required: `False`
+- Write action required: `False`
+- Application form submission performed: `False`
+- PyPI publish performed: `False`
+- Third-party pull request, issue comment, or funded-issue claim performed:
+  `False`
+"""
+
+
+def build_reviewer_quick_check(*, root: Path, out_dir: Path | None = None) -> str:
+    doctor = _run_patchrail(["doctor", "--format", "text"], root=root)
+    ci_report = _run_patchrail(
+        [
+            "ci",
+            "explain",
+            "--log",
+            "examples/ci-triage/dependency-failure.log",
+            "--format",
+            "markdown",
+        ],
+        root=root,
+    )
+    release_readiness_json = _run_patchrail(
+        ["evidence", "release-readiness", "--clean-dist", "--format", "json"],
+        root=root,
+    )
+    release_readiness_text = _release_readiness_markdown(json.loads(release_readiness_json.stdout))
+    control_plane = _run_patchrail(
+        ["evidence", "control-plane", "--format", "markdown"],
+        root=root,
+    )
+    control_plane_json = _run_patchrail(
+        ["evidence", "control-plane", "--format", "json"],
+        root=root,
+    )
+    http_api = _run_patchrail(
+        ["evidence", "http-api", "--format", "markdown"],
+        root=root,
+    )
+    http_api_json = _run_patchrail(
+        ["evidence", "http-api", "--format", "json"],
+        root=root,
+    )
+    gate = _run_patchrail(
+        ["evidence", "application-gate", "--format", "text"],
+        root=root,
+        allow_nonzero=True,
+    )
+    dossier = _run_patchrail(["evidence", "application-dossier", "--format", "text"], root=root)
+    dossier_json = _run_patchrail(
+        ["evidence", "application-dossier", "--format", "json"], root=root
+    )
+    dossier_schema = _run_patchrail(["schema", "application-dossier"], root=root)
+    reviewer_packet_schema = _run_patchrail(["schema", "reviewer-quick-check-artifacts"], root=root)
+
+    lines = [
+        "# PatchRail Reviewer Quick Check",
+        "",
+        "This local smoke test uses the checked-out source tree only. It does not",
+        "publish to PyPI, create pull requests, post comments, claim funding, call",
+        "external models, or require GitHub write permissions.",
+        "",
+        "## 1. Local Doctor",
+        "",
+        _fenced("text", doctor.stdout),
+        "",
+        "## 2. CI Triage Demo",
+        "",
+        _fenced(
+            "bash",
+            (
+                "uv run --extra dev patchrail ci explain --log "
+                "examples/ci-triage/dependency-failure.log --format markdown"
+            ),
+        ),
+        "",
+        _fenced("markdown", ci_report.stdout),
+        "",
+        "## 3. Release Readiness Evidence",
+        "",
+        "This local evidence builds and smoke-tests release artifacts, but leaves",
+        "PyPI publish, release tagging, public announcements, and external program",
+        "submission behind manual gates.",
+        "",
+        _fenced("markdown", release_readiness_text),
+        "",
+        "## 4. Agent Control Plane Evidence",
+        "",
+        "The local queue demo must be ready for reviewer handoff, exercise human",
+        "approval gates, and keep execution disabled.",
+        "",
+        _fenced("markdown", control_plane.stdout),
+        "",
+        "## 5. HTTP API Evidence",
+        "",
+        "The local HTTP smoke starts an ephemeral loopback server, exercises the",
+        "public endpoints, records approval/rejection decisions, and confirms",
+        "that write actions remain locked.",
+        "",
+        _fenced("markdown", http_api.stdout),
+        "",
+        "## 6. Application Gate",
+        "",
+        "The gate is expected to fail closed until public evidence is real.",
+        "",
+        _fenced("text", gate.stdout),
+        "",
+        "## 7. Application Dossier Contract",
+        "",
+        "The dossier is a local draft artifact. It does not submit the external",
+        "application and keeps maintainer tap required.",
+        "",
+        _fenced("text", dossier.stdout),
+        "",
+        "Schema smoke:",
+        "",
+        _fenced("json", dossier_schema.stdout),
+        "",
+        "Reviewer packet manifest schema smoke:",
+        "",
+        _fenced("json", reviewer_packet_schema.stdout),
+        "",
+    ]
+    written_artifacts: list[str] = []
+    if out_dir:
+        base_artifacts = _write_artifacts(
+            out_dir,
+            ci_report=ci_report.stdout,
+            release_readiness_text=release_readiness_text,
+            release_readiness_json=release_readiness_json.stdout,
+            control_plane_text=control_plane.stdout,
+            control_plane_json=control_plane_json.stdout,
+            http_api_text=http_api.stdout,
+            http_api_json=http_api_json.stdout,
+            gate_text=gate.stdout,
+            dossier_text=dossier.stdout,
+            dossier_json=dossier_json.stdout,
+            dossier_schema=dossier_schema.stdout,
+            reviewer_packet_schema=reviewer_packet_schema.stdout,
+        )
+        written_artifacts = ["reviewer-quick-check.md", "artifact-index.md", *base_artifacts]
+        lines.extend(
+            [
+                "## 8. Artifact Packet",
+                "",
+                f"Output directory: `{_display_path(out_dir, root=root)}`",
+                "",
+                *[f"- `{name}`" for name in [*written_artifacts, "manifest.json"]],
+                "",
+            ]
+        )
+
+    lines.extend(
+        [
+            "## Result",
+            "",
+            "- Reviewer demo generated: `True`",
+            "- Release readiness evidence generated: `True`",
+            "- Agent Control Plane evidence generated: `True`",
+            "- HTTP API evidence generated: `True`",
+            "- Application dossier generated: `True`",
+            "- Application dossier schema available: `True`",
+            "- Reviewer packet manifest schema available: `True`",
+            f"- Artifact packet generated: `{'True' if written_artifacts else 'False'}`",
+            "- Network required: `False`",
+            "- Write action required: `False`",
+            "- Application form submission performed: `False`",
+        ]
+    )
+    final_output = "\n".join(lines)
+    if out_dir:
+        (out_dir / "reviewer-quick-check.md").write_text(final_output + "\n", encoding="utf-8")
+        _write_artifact_index(out_dir, ["reviewer-quick-check.md", *base_artifacts])
+        _write_manifest(out_dir, written_artifacts)
+    return final_output + "\n"
+
+
+def main(argv: list[str] | None = None, *, root: Path | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate a local PatchRail reviewer quick check packet."
+    )
+    parser.add_argument(
+        "--out-dir",
+        type=Path,
+        help="Optional directory for reviewer-facing Markdown/JSON artifacts.",
+    )
+    args = parser.parse_args(argv)
+    print(build_reviewer_quick_check(root=root or Path("."), out_dir=args.out_dir), end="")
+    return 0

patchrail/schemas/__init__.py

@@ -0,0 +1 @@
+"""Versioned JSON schemas bundled with PatchRail."""