proofside 0.1.0__py3-none-any.whl

proofside/__init__.py

@@ -0,0 +1,3 @@
+"""Proofside's deliberately small Nagini command-line wrapper."""
+
+

proofside/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

proofside/acceptance.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .artifacts import accepted_contract_path, candidate_contract_path
+from .cli import CheckResult, _function_arguments, load_target, parse_selector
+from .contracts import ContractError, parse_contract, render_human, validate_contract
+
+
+class AcceptanceError(ValueError):
+    pass
+
+
+def accept_contract(
+    selector: str,
+    candidate_path: Path | None = None,
+    replace: bool = False,
+) -> tuple[str, Path, Path]:
+    try:
+        file_path, function_name = parse_selector(selector)
+    except ValueError as error:
+        raise AcceptanceError(str(error)) from error
+    target = load_target(file_path, function_name, require_inline_contract=False)
+    if isinstance(target, CheckResult):
+        raise AcceptanceError(f"{target.status.value}: {target.detail}")
+    _source, function = target
+
+    candidate_path = candidate_path or candidate_contract_path(file_path, function_name)
+    output_path = accepted_contract_path(file_path, function_name)
+    if output_path.exists() and not replace:
+        raise AcceptanceError(f"accepted contract already exists: {output_path}; use --replace")
+
+    try:
+        candidate_text = candidate_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as error:
+        raise AcceptanceError(f"could not read candidate contract {candidate_path}: {error}") from error
+    try:
+        data = json.loads(candidate_text)
+    except json.JSONDecodeError as error:
+        raise AcceptanceError(
+            f"malformed candidate JSON at line {error.lineno}: {error.msg}"
+        ) from error
+    try:
+        contract = parse_contract(data)
+        parameters = {argument.arg for argument in _function_arguments(function)}
+        validate_contract(contract, parameters)
+    except ContractError as error:
+        raise AcceptanceError(f"invalid candidate contract: {error}") from error
+
+    accepted_text = json.dumps(data, indent=2) + "\n"
+    try:
+        output_path.parent.mkdir(exist_ok=True)
+        mode = "w" if replace else "x"
+        with output_path.open(mode, encoding="utf-8") as output_file:
+            output_file.write(accepted_text)
+    except FileExistsError as error:
+        raise AcceptanceError(f"accepted contract already exists: {output_path}; use --replace") from error
+    except OSError as error:
+        raise AcceptanceError(f"could not save accepted contract: {error}") from error
+
+    return render_human(contract), candidate_path, output_path
+
+
+def render_acceptance_output(
+    contract_text: str,
+    candidate_path: Path,
+    accepted_path: Path,
+) -> str:
+    return (
+        "ACCEPTED FOR VERIFICATION — NOT VERIFIED\n\n"
+        f"Contract\n\n{contract_text}\n\n"
+        f"Candidate:\n{candidate_path}\n\n"
+        f"Accepted contract:\n{accepted_path}\n\n"
+        "This records explicit user acceptance of the contract for verification.\n"
+        "No verification was run."
+    )

proofside/artifacts.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+
+def candidate_contract_path(file_path: Path, function_name: str) -> Path:
+    return file_path.parent / ".proofside" / f"{file_path.stem}.{function_name}.candidate.json"
+
+
+def accepted_contract_path(file_path: Path, function_name: str) -> Path:
+    return file_path.parent / ".proofside" / f"{file_path.stem}.{function_name}.contract.json"

proofside/batch.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import tokenize
+
+from .artifacts import accepted_contract_path, candidate_contract_path
+from .cli import CheckResult, Status, check
+from .proposal import ProposalError, propose_contract
+from .specification import (
+    SpecificationAnnotationError,
+    marked_functions_in_source,
+    specification_annotations_for_function,
+)
+
+
+@dataclass(frozen=True)
+class BatchCheckResult:
+    selector: str
+    result: CheckResult | None = None
+    contract_path: Path | None = None
+    unreviewed: bool = False
+    issue: str | None = None
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class MarkedTarget:
+    file_path: Path
+    source: str
+    function: ast.FunctionDef
+
+    @property
+    def selector(self) -> str:
+        return f"{self.file_path}::{self.function.name}"
+
+
+@dataclass(frozen=True)
+class BatchProposalResult:
+    selector: str
+    candidate_path: Path
+    sources: tuple[str, ...] = ()
+    proposed: bool = False
+    issue: str | None = None
+    detail: str = ""
+
+
+def discover_python_files(
+    targets: tuple[Path, ...],
+) -> tuple[tuple[Path, ...], tuple[tuple[Path, str], ...]]:
+    files: dict[Path, Path] = {}
+    errors = []
+    for target in targets:
+        if target.is_file():
+            if target.suffix != ".py":
+                errors.append((target, "target is not a Python file"))
+            else:
+                files.setdefault(target.resolve(), target)
+            continue
+        if not target.is_dir():
+            errors.append((target, "target does not exist"))
+            continue
+        if target.name.startswith("."):
+            continue
+
+        walk_errors = []
+        for directory, subdirectories, names in os.walk(
+            target,
+            onerror=walk_errors.append,
+        ):
+            subdirectories[:] = sorted(
+                name for name in subdirectories if not name.startswith(".")
+            )
+            for name in sorted(names):
+                if name.endswith(".py"):
+                    path = Path(directory, name)
+                    files.setdefault(path.resolve(), path)
+        errors.extend((Path(error.filename or target), str(error)) for error in walk_errors)
+
+    paths = tuple(sorted(files.values(), key=lambda path: path.as_posix()))
+    return paths, tuple(errors)
+
+
+def discover_marked_targets(
+    targets: tuple[Path, ...],
+) -> tuple[tuple[MarkedTarget, ...], tuple[tuple[Path, str], ...]]:
+    files, discovery_errors = discover_python_files(targets)
+    marked_targets = []
+    errors = list(discovery_errors)
+    for file_path in files:
+        try:
+            source = file_path.read_text(encoding="utf-8")
+            functions = marked_functions_in_source(source)
+        except (OSError, UnicodeError, SyntaxError, tokenize.TokenError) as error:
+            errors.append((file_path, _discovery_error_detail(error)))
+            continue
+        marked_targets.extend(
+            MarkedTarget(file_path, source, function) for function in functions
+        )
+    return tuple(marked_targets), tuple(errors)
+
+
+def run_batch_checks(
+    targets: tuple[Path, ...],
+    allow_unreviewed: bool = False,
+) -> tuple[tuple[BatchCheckResult, ...], tuple[tuple[Path, str], ...]]:
+    marked_targets, discovery_errors = discover_marked_targets(targets)
+    results = []
+
+    for target in marked_targets:
+        try:
+            specification_annotations_for_function(target.source, target.function)
+        except SpecificationAnnotationError as error:
+            results.append(
+                BatchCheckResult(
+                    target.selector,
+                    issue="INVALID SPECIFICATION",
+                    detail=str(error),
+                )
+            )
+            continue
+
+        accepted_path = accepted_contract_path(target.file_path, target.function.name)
+        candidate_path = candidate_contract_path(target.file_path, target.function.name)
+        if accepted_path.is_file():
+            contract_path = accepted_path
+            unreviewed = False
+        elif allow_unreviewed and candidate_path.is_file():
+            contract_path = candidate_path
+            unreviewed = True
+        else:
+            issue = "NO CONTRACT" if allow_unreviewed else "NO ACCEPTED CONTRACT"
+            detail = str(candidate_path if allow_unreviewed else accepted_path)
+            results.append(BatchCheckResult(target.selector, issue=issue, detail=detail))
+            continue
+
+        results.append(
+            BatchCheckResult(
+                target.selector,
+                check(target.selector, contract_path),
+                contract_path,
+                unreviewed,
+            )
+        )
+    return tuple(results), discovery_errors
+
+
+def run_batch_proposals(
+    targets: tuple[Path, ...],
+    model_source: str,
+    model: str,
+    base_url: str | None = None,
+    api_key_env: str | None = None,
+    sources: tuple[str, ...] | None = None,
+) -> tuple[tuple[BatchProposalResult, ...], tuple[tuple[Path, str], ...]]:
+    marked_targets, discovery_errors = discover_marked_targets(targets)
+    results = []
+    for target in marked_targets:
+        output_path = candidate_contract_path(target.file_path, target.function.name)
+        if output_path.exists():
+            results.append(
+                BatchProposalResult(
+                    target.selector,
+                    output_path,
+                    issue="CANDIDATE EXISTS",
+                    detail=str(output_path),
+                )
+            )
+            continue
+        try:
+            _contract_text, used_sources = propose_contract(
+                target.selector,
+                model_source,
+                model,
+                None,
+                base_url,
+                api_key_env,
+                sources,
+            )
+        except ProposalError as error:
+            results.append(
+                BatchProposalResult(
+                    target.selector,
+                    output_path,
+                    issue="PROPOSAL REJECTED",
+                    detail=str(error),
+                )
+            )
+            continue
+        results.append(
+            BatchProposalResult(
+                target.selector,
+                output_path,
+                used_sources,
+                proposed=True,
+            )
+        )
+    return tuple(results), discovery_errors
+
+
+def _discovery_error_detail(error: BaseException) -> str:
+    if isinstance(error, SyntaxError):
+        location = f"line {error.lineno}" if error.lineno else "unknown line"
+        return f"cannot parse ({location}): {error.msg}"
+    return str(error)
+
+
+def batch_succeeded(
+    results: tuple[BatchCheckResult, ...],
+    discovery_errors: tuple[tuple[Path, str], ...],
+) -> bool:
+    return bool(results) and not discovery_errors and all(
+        item.result is not None
+        and item.result.status is Status.VERIFIED
+        and not item.unreviewed
+        for item in results
+    )
+
+
+def batch_proposal_succeeded(
+    results: tuple[BatchProposalResult, ...],
+    discovery_errors: tuple[tuple[Path, str], ...],
+) -> bool:
+    return bool(results) and not discovery_errors and all(
+        item.proposed for item in results
+    )
+
+
+def render_batch_output(
+    results: tuple[BatchCheckResult, ...],
+    discovery_errors: tuple[tuple[Path, str], ...],
+) -> str:
+    total = len(results)
+    verified = sum(
+        item.result is not None and item.result.status is Status.VERIFIED
+        for item in results
+    )
+    lines = ["Proofside batch", ""]
+    if not total:
+        lines.append("0 Proofside-marked functions found")
+    else:
+        lines.extend((f"{total} Proofside-marked functions", f"{verified}/{total} VERIFIED"))
+
+    groups: dict[str, list[tuple[str, str]]] = {}
+    for item in results:
+        if item.issue:
+            category = item.issue
+            detail = item.detail
+        elif item.unreviewed:
+            category = f"{item.result.status.value} (UNREVIEWED CONTRACT)"
+            detail = str(item.contract_path)
+        elif item.result.status is not Status.VERIFIED:
+            category = item.result.status.value
+            detail = item.result.detail
+        else:
+            continue
+        groups.setdefault(category, []).append((item.selector, detail))
+    if discovery_errors:
+        groups["DISCOVERY ERROR"] = [
+            (str(path), detail) for path, detail in discovery_errors
+        ]
+
+    for category, items in groups.items():
+        lines.extend(("", category))
+        for selector, detail in items:
+            lines.append(f"- {selector}")
+            if detail:
+                lines.append(f"  {detail}")
+    return "\n".join(lines)
+
+
+def render_batch_proposal_output(
+    results: tuple[BatchProposalResult, ...],
+    discovery_errors: tuple[tuple[Path, str], ...],
+) -> str:
+    total = len(results)
+    proposed = sum(item.proposed for item in results)
+    lines = ["Proofside batch proposal", ""]
+    if not total:
+        lines.append("0 Proofside-marked functions found")
+    else:
+        lines.extend((f"{total} Proofside-marked functions", f"{proposed}/{total} PROPOSED"))
+
+    groups: dict[str, list[tuple[str, str]]] = {}
+    for item in results:
+        if item.issue:
+            groups.setdefault(item.issue, []).append((item.selector, item.detail))
+    if discovery_errors:
+        groups["DISCOVERY ERROR"] = [
+            (str(path), detail) for path, detail in discovery_errors
+        ]
+
+    for category, items in groups.items():
+        lines.extend(("", category))
+        for selector, detail in items:
+            lines.append(f"- {selector}")
+            if detail:
+                lines.append(f"  {detail}")
+    if proposed:
+        lines.extend(
+            (
+                "",
+                "Candidates were saved under source-adjacent .proofside/ directories.",
+                "Review or edit them, then accept explicitly before check-all.",
+            )
+        )
+    return "\n".join(lines)