PTSIP 0.3.1__py3-none-any.whl

ptsip/clarification/render.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from .i18n import question, text
+from .model import ClarificationRequest
+
+
+def request_payload(request: ClarificationRequest, language: str) -> dict[str, object]:
+    payload = request.as_dict()
+    payload["questions"] = [question(field, language) for field in request.missing_fields]
+    return payload
+
+
+def render_issue(request: ClarificationRequest, language: str, repository_revision: str | None) -> tuple[str, str]:
+    title = text(language, "title", component_id=request.component_id)
+    paths = "\n".join(f"- `{item}`" for item in request.include) or "- `<unknown>`"
+    reasons = "\n".join(f"- `{item}`" for item in request.reason_codes)
+    questions: list[str] = []
+    for index, field in enumerate(request.missing_fields, start=1):
+        item = question(field, language)
+        lines = [f"{index}. {item['prompt']}"]
+        for option in item.get("options", []):
+            lines.append(f"   - `{option['value']}` — {option['label']}")
+        questions.append("\n".join(lines))
+    reply_lines = [
+        "format: ptsip-clarification-answer/v1",
+        "decision:",
+        "  classification: PRODUCT|TOOLCHAIN|NEUTRAL_CONTRACT",
+        '  purpose: "<short description>"',
+        "  shipped: YES|NO",
+        "  runtime_required: YES|NO",
+        "  lifecycle_owner: PRODUCT|DEVELOPMENT_TOOLING|INDEPENDENT",
+        "  executable: YES|NO",
+    ]
+    revision = repository_revision or "UNKNOWN"
+    body = f"""{text(language, 'intro')}
+
+{text(language, 'no_llm')}
+
+### Component
+- ID: `{request.component_id}`
+- Repository revision: `{revision}`
+- Candidate paths:
+{paths}
+
+### Why PTSIP is asking
+{reasons}
+
+### Questions
+
+{chr(10).join(questions)}
+
+### Structured reply
+
+{text(language, 'reply')}
+
+```yaml
+{chr(10).join(reply_lines)}
+```
+
+A coding agent may also resolve this decision in an active user chat. The first valid resolution wins; after the decision is resolved, late Issue replies are ignored.
+
+<!-- ptsip-clarification-id: {request.id} -->
+"""
+    return title, body
+
+
+def render_console(requests: tuple[ClarificationRequest, ...], language: str) -> str:
+    if not requests:
+        return text(language, "none")
+    lines = [f"{text(language, 'required')}: {len(requests)}"]
+    for request in requests:
+        lines.append("")
+        lines.append(f"{request.component_id} [{request.status.value}]")
+        for path in request.include:
+            lines.append(f"  path: {path}")
+        for field in request.missing_fields:
+            lines.append(f"  - {question(field, language)['prompt']}")
+    return "\n".join(lines)

ptsip/clarification/resolution/__init__.py

@@ -0,0 +1,29 @@
+from .model import DecisionAnswer, ResolutionValidation
+from .parser import ANSWER_FORMAT, parse_answer
+from .profile_projection import (
+    PreparedLocalProfile,
+    apply_local_profile,
+    dump_payload,
+    load_profile_text,
+    prepare_local_profile,
+    project_payload,
+    validate_projected_payload,
+    write_prepared_local_profile,
+)
+from .resolver import validate_answer
+
+__all__ = [
+    "ANSWER_FORMAT",
+    "DecisionAnswer",
+    "PreparedLocalProfile",
+    "ResolutionValidation",
+    "apply_local_profile",
+    "dump_payload",
+    "load_profile_text",
+    "parse_answer",
+    "prepare_local_profile",
+    "project_payload",
+    "validate_answer",
+    "validate_projected_payload",
+    "write_prepared_local_profile",
+]

ptsip/clarification/resolution/model.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+CLASSIFICATIONS = ("PRODUCT", "TOOLCHAIN", "NEUTRAL_CONTRACT")
+LIFECYCLE_OWNERS = ("PRODUCT", "DEVELOPMENT_TOOLING", "INDEPENDENT")
+
+
+@dataclass(frozen=True)
+class DecisionAnswer:
+    classification: str
+    purpose: str
+    shipped: bool
+    runtime_required: bool
+    lifecycle_owner: str
+    executable: bool
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class ResolutionValidation:
+    valid: bool
+    status: str
+    errors: tuple[str, ...]
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "valid": self.valid,
+            "status": self.status,
+            "errors": list(self.errors),
+        }

ptsip/clarification/resolution/parser.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import re
+
+import yaml
+
+from .model import DecisionAnswer
+
+ANSWER_FORMAT = "ptsip-clarification-answer/v1"
+
+
+def _boolean(value: object, field: str) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().upper()
+        if normalized in {"YES", "TRUE"}:
+            return True
+        if normalized in {"NO", "FALSE"}:
+            return False
+    raise ValueError(f"{field} must be YES or NO")
+
+
+def _mapping(text: str) -> dict[str, object]:
+    blocks = re.findall(r"```(?:ya?ml)?\s*\n(.*?)```", text, flags=re.IGNORECASE | re.DOTALL)
+    candidates = [*reversed(blocks), text]
+    for candidate in candidates:
+        try:
+            payload = yaml.safe_load(candidate)
+        except yaml.YAMLError:
+            continue
+        if isinstance(payload, dict):
+            if payload.get("format") == ANSWER_FORMAT or isinstance(payload.get("decision"), dict):
+                return payload
+    raise ValueError("No structured PTSIP clarification answer was found")
+
+
+def parse_answer(text: str) -> DecisionAnswer:
+    payload = _mapping(text)
+    if payload.get("format") not in (None, ANSWER_FORMAT):
+        raise ValueError(f"format must be {ANSWER_FORMAT!r}")
+    raw = payload.get("decision", payload)
+    if not isinstance(raw, dict):
+        raise ValueError("decision must be a mapping")
+    classification = str(raw.get("classification", "")).strip().upper()
+    purpose = str(raw.get("purpose", "")).strip()
+    lifecycle_owner = str(raw.get("lifecycle_owner", "")).strip().upper()
+    executable = _boolean(raw.get("executable"), "executable")
+    return DecisionAnswer(
+        classification=classification,
+        purpose=purpose,
+        shipped=_boolean(raw.get("shipped"), "shipped"),
+        runtime_required=_boolean(raw.get("runtime_required"), "runtime_required"),
+        lifecycle_owner=lifecycle_owner,
+        executable=executable,
+    )

ptsip/clarification/resolution/profile_projection.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import copy
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+from jsonschema import Draft202012Validator
+
+from ...constants import SPEC_REVISION, SPEC_SOURCE, SPEC_VERSION
+from ...validation.profile import _root_overlap_errors, _schema, validate_profile
+from .model import DecisionAnswer
+
+DEFAULT_POLICIES: dict[str, str] = {
+    "product_to_toolchain_runtime_dependency": "deny",
+    "toolchain_in_product_package": "deny",
+    "independent_build_resolution": "required",
+}
+
+
+@dataclass(frozen=True)
+class PreparedLocalProfile:
+    path: Path
+    content: str
+    expected_source: str | None
+
+
+def _base_profile() -> dict[str, object]:
+    return {
+        "ptsip": {
+            "version": SPEC_VERSION,
+            "specification": {
+                "source": SPEC_SOURCE,
+                "revision": SPEC_REVISION,
+            },
+        },
+        "components": [],
+        "policies": dict(DEFAULT_POLICIES),
+    }
+
+
+def _boundary_root(selector: str) -> str:
+    normalized = selector.replace("\\", "/").strip().strip("/")
+    if normalized.endswith("/**"):
+        normalized = normalized[:-3].rstrip("/")
+    if not normalized or any(char in normalized for char in "*?[]"):
+        raise ValueError(f"Boundary profile cannot safely represent selector {selector!r}")
+    return normalized
+
+
+def _set_missing_or_require_equal(component: dict[str, object], key: str, expected: object) -> None:
+    if key not in component or component[key] in (None, ""):
+        component[key] = expected
+        return
+    if component[key] != expected:
+        raise ValueError(
+            f"Existing component {component.get('id')!r} declares {key}={component[key]!r}, "
+            f"which conflicts with the resolved decision value {expected!r}"
+        )
+
+
+def project_payload(
+    existing: dict[str, object] | None,
+    component_id: str,
+    include: tuple[str, ...] | list[str],
+    answer: DecisionAnswer,
+) -> dict[str, object]:
+    payload = copy.deepcopy(existing) if existing is not None else _base_profile()
+    if not isinstance(payload, dict):
+        raise ValueError("PTSIP profile root must be a mapping")
+
+    if "boundaries" in payload and "components" not in payload:
+        boundaries = payload.get("boundaries")
+        if not isinstance(boundaries, dict):
+            raise ValueError("boundaries must be a mapping")
+        key = {
+            "PRODUCT": "product",
+            "TOOLCHAIN": "toolchain",
+            "NEUTRAL_CONTRACT": "neutral_contract",
+        }[answer.classification]
+        target = boundaries.setdefault(key, {"roots": []})
+        if not isinstance(target, dict):
+            raise ValueError(f"boundaries.{key} must be a mapping")
+        roots = target.setdefault("roots", [])
+        if not isinstance(roots, list):
+            raise ValueError(f"boundaries.{key}.roots must be a list")
+        for selector in include:
+            root = _boundary_root(str(selector))
+            if root not in roots:
+                roots.append(root)
+        return payload
+
+    components = payload.setdefault("components", [])
+    if not isinstance(components, list):
+        raise ValueError("components must be a list")
+    payload.pop("boundaries", None)
+
+    component: dict[str, object] | None = None
+    for item in components:
+        if isinstance(item, dict) and str(item.get("id")) == component_id:
+            component = item
+            break
+    if component is None:
+        component = {"id": component_id, "include": [str(item) for item in include]}
+        components.append(component)
+    elif "include" not in component:
+        component["include"] = [str(item) for item in include]
+
+    # Clarification fills missing declaration facts. It must not silently
+    # reclassify or rewrite facts the profile already declares. Existing
+    # include selectors are preserved so resolving one detected candidate does
+    # not accidentally narrow a broader project-owned component boundary.
+    _set_missing_or_require_equal(component, "classification", answer.classification)
+    _set_missing_or_require_equal(component, "purpose", answer.purpose)
+    _set_missing_or_require_equal(component, "shipped", answer.shipped)
+    _set_missing_or_require_equal(component, "executable", answer.executable)
+    _set_missing_or_require_equal(component, "release_owner", answer.lifecycle_owner)
+    return payload
+
+
+def validate_projected_payload(payload: dict[str, object]) -> tuple[str, ...]:
+    errors = [
+        f"{'.'.join(str(part) for part in item.absolute_path) or '<root>'}: {item.message}"
+        for item in sorted(Draft202012Validator(_schema()).iter_errors(payload), key=lambda value: list(value.absolute_path))
+    ]
+    errors.extend(_root_overlap_errors(payload))
+    return tuple(errors)
+
+
+def dump_payload(payload: dict[str, object]) -> str:
+    return yaml.safe_dump(payload, sort_keys=False, allow_unicode=True)
+
+
+def load_profile_text(text: str | None) -> dict[str, object] | None:
+    if text is None:
+        return None
+    payload = yaml.safe_load(text)
+    if not isinstance(payload, dict):
+        raise ValueError("PTSIP profile root must be a mapping")
+    return payload
+
+
+def prepare_local_profile(
+    repository_root: str | Path,
+    component_id: str,
+    include: tuple[str, ...] | list[str],
+    answer: DecisionAnswer,
+) -> PreparedLocalProfile:
+    root = Path(repository_root).resolve()
+    profile = root / "ptsip.yaml"
+    expected_source = profile.read_text(encoding="utf-8-sig") if profile.is_file() else None
+    existing = load_profile_text(expected_source)
+    projected = project_payload(existing, component_id, include, answer)
+    content = dump_payload(projected)
+
+    with tempfile.NamedTemporaryFile("w", suffix=".yaml", dir=root, delete=False, encoding="utf-8", newline="\n") as handle:
+        temp = Path(handle.name)
+        handle.write(content)
+    try:
+        result = validate_profile(root, temp)
+        if not result.valid:
+            raise ValueError("Projected PTSIP profile is invalid: " + "; ".join(result.errors))
+    finally:
+        if temp.exists():
+            temp.unlink()
+    return PreparedLocalProfile(profile, content, expected_source)
+
+
+def write_prepared_local_profile(prepared: PreparedLocalProfile) -> Path:
+    current_source = prepared.path.read_text(encoding="utf-8-sig") if prepared.path.is_file() else None
+    if current_source != prepared.expected_source:
+        raise RuntimeError("ptsip.yaml changed after decision projection validation; refusing to overwrite concurrent changes")
+    with tempfile.NamedTemporaryFile(
+        "w",
+        suffix=".yaml",
+        dir=prepared.path.parent,
+        delete=False,
+        encoding="utf-8",
+        newline="\n",
+    ) as handle:
+        temp = Path(handle.name)
+        handle.write(prepared.content)
+    try:
+        temp.replace(prepared.path)
+    finally:
+        if temp.exists():
+            temp.unlink()
+    return prepared.path
+
+
+def apply_local_profile(
+    repository_root: str | Path,
+    component_id: str,
+    include: tuple[str, ...] | list[str],
+    answer: DecisionAnswer,
+) -> Path:
+    return write_prepared_local_profile(prepare_local_profile(repository_root, component_id, include, answer))

ptsip/clarification/resolution/resolver.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .model import CLASSIFICATIONS, LIFECYCLE_OWNERS, DecisionAnswer, ResolutionValidation
+
+
+def validate_answer(answer: DecisionAnswer) -> ResolutionValidation:
+    errors: list[str] = []
+    if answer.classification not in CLASSIFICATIONS:
+        errors.append("classification must be PRODUCT, TOOLCHAIN, or NEUTRAL_CONTRACT")
+    if not answer.purpose:
+        errors.append("purpose must be non-empty")
+    if answer.lifecycle_owner not in LIFECYCLE_OWNERS:
+        errors.append("lifecycle_owner must be PRODUCT, DEVELOPMENT_TOOLING, or INDEPENDENT")
+
+    if answer.classification == "PRODUCT" and answer.lifecycle_owner != "PRODUCT":
+        errors.append("PRODUCT classification requires PRODUCT lifecycle ownership")
+    if answer.classification == "TOOLCHAIN":
+        if answer.lifecycle_owner != "DEVELOPMENT_TOOLING":
+            errors.append("TOOLCHAIN classification requires DEVELOPMENT_TOOLING lifecycle ownership")
+        if answer.shipped:
+            errors.append("TOOLCHAIN component cannot be declared as shipped with the Product")
+        if answer.runtime_required:
+            errors.append("TOOLCHAIN component cannot be required by the Product at runtime")
+    if answer.classification == "NEUTRAL_CONTRACT":
+        if answer.executable:
+            errors.append("NEUTRAL_CONTRACT must be non-executable")
+        if answer.lifecycle_owner != "INDEPENDENT":
+            errors.append("NEUTRAL_CONTRACT requires INDEPENDENT lifecycle ownership")
+
+    return ResolutionValidation(not errors, "RESOLVED" if not errors else "CONFLICT", tuple(errors))

ptsip/clarification/transports/__init__.py

@@ -0,0 +1 @@
+"""Explicit side-effect transports for PTSIP clarification requests."""

ptsip/clarification/transports/github_issue.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from ...repository.remote import RepositoryRemote
+from ...storage.local_state import clarification_directory
+from ..model import ClarificationRequest
+from ..render import render_issue
+
+
+@dataclass(frozen=True)
+class GitHubIssuePublication:
+    clarification_id: str
+    component_id: str
+    repository: str
+    status: str
+    issue_number: int | None
+    issue_url: str
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def _valid_repo(value: str) -> bool:
+    return bool(re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", value.strip()))
+
+
+def resolve_repository(remote: RepositoryRemote | None, override: str | None) -> str:
+    if override:
+        target = override.strip()
+        if not _valid_repo(target):
+            raise ValueError("--repo must use GitHub owner/repository form")
+        return target
+    if remote and remote.provider == "github" and remote.repository:
+        return remote.repository
+    raise RuntimeError(
+        "No GitHub origin was detected. Use --repo owner/repository to select the Consumer Repository explicitly."
+    )
+
+
+def _state_path(repository_root: str | Path) -> Path:
+    return clarification_directory(repository_root) / "state.json"
+
+
+def _load_state(repository_root: str | Path) -> dict[str, object]:
+    path = _state_path(repository_root)
+    if not path.exists():
+        return {"format": "ptsip-clarification-state/v1", "issues": {}}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RuntimeError(f"Unable to read clarification state: {exc}") from exc
+    if not isinstance(payload, dict) or not isinstance(payload.get("issues"), dict):
+        raise RuntimeError("Clarification state is not a valid ptsip-clarification-state/v1 document.")
+    return payload
+
+
+def _save_state(repository_root: str | Path, state: dict[str, object]) -> None:
+    path = _state_path(repository_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_suffix(".tmp")
+    temp.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    temp.replace(path)
+
+
+def _run_gh(args: list[str], input_text: str | None = None) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["gh", *args],
+        input=input_text,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+
+
+def _issue_number(url: str) -> int | None:
+    match = re.search(r"/issues/(\d+)(?:$|[/?#])", url)
+    return int(match.group(1)) if match else None
+
+
+def publish(
+    repository_root: str | Path,
+    remote: RepositoryRemote | None,
+    repository_revision: str | None,
+    requests: tuple[ClarificationRequest, ...],
+    language: str,
+    repo_override: str | None = None,
+) -> tuple[GitHubIssuePublication, ...]:
+    if not requests:
+        return ()
+    target = resolve_repository(remote, repo_override)
+    state = _load_state(repository_root)
+    issues = state["issues"]
+    assert isinstance(issues, dict)
+    needs_create = any(
+        not (
+            isinstance(issues.get(request.id), dict)
+            and issues[request.id].get("repository") == target
+            and issues[request.id].get("url")
+        )
+        for request in requests
+    )
+    if needs_create:
+        if shutil.which("gh") is None:
+            raise RuntimeError("GitHub CLI 'gh' is required for --publish github-issue.")
+        auth = _run_gh(["auth", "status", "--hostname", "github.com"])
+        if auth.returncode != 0:
+            detail = auth.stderr.strip() or auth.stdout.strip() or "authentication failed"
+            raise RuntimeError(f"GitHub CLI authentication is not ready: {detail}")
+
+    results: list[GitHubIssuePublication] = []
+    for request in requests:
+        existing = issues.get(request.id)
+        if isinstance(existing, dict) and existing.get("repository") == target and existing.get("url"):
+            results.append(
+                GitHubIssuePublication(
+                    clarification_id=request.id,
+                    component_id=request.component_id,
+                    repository=target,
+                    status="EXISTING",
+                    issue_number=existing.get("number") if isinstance(existing.get("number"), int) else None,
+                    issue_url=str(existing["url"]),
+                )
+            )
+            continue
+
+        title, body = render_issue(request, language, repository_revision)
+        created = _run_gh(
+            ["issue", "create", "--repo", target, "--title", title, "--body-file", "-"],
+            input_text=body,
+        )
+        if created.returncode != 0:
+            detail = created.stderr.strip() or created.stdout.strip() or "issue creation failed"
+            raise RuntimeError(f"GitHub issue creation failed for {request.component_id}: {detail}")
+        url = next((line.strip() for line in reversed(created.stdout.splitlines()) if line.strip()), "")
+        if not url:
+            raise RuntimeError(f"GitHub issue creation returned no issue URL for {request.component_id}.")
+        number = _issue_number(url)
+        issues[request.id] = {
+            "repository": target,
+            "number": number,
+            "url": url,
+            "component_id": request.component_id,
+        }
+        _save_state(repository_root, state)
+        results.append(
+            GitHubIssuePublication(
+                clarification_id=request.id,
+                component_id=request.component_id,
+                repository=target,
+                status="CREATED",
+                issue_number=number,
+                issue_url=url,
+            )
+        )
+    return tuple(results)