PTSIP 0.3.1__py3-none-any.whl

ptsip/conformance_engine.py

@@ -0,0 +1,396 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import yaml
+
+from .build_resolution import evaluate_independent_build_resolution
+from .conformance import (
+    ConformanceResult,
+    _dependency_coverage_gaps,
+    _finding_diagnostic,
+    _unassigned_coverage_gaps,
+    _unsupported_source_coverage_gaps,
+    evaluate_conformance as evaluate_base_conformance,
+)
+from .conformance_audit import audit_conformance_report
+from .inspection.dependencies import DependencyScan
+from .inspection.dependencies_030 import scan_dependency_edges
+from .inspection.source_adapters import SUPPORTED_SOURCE_SUFFIXES
+from .lifecycle_evidence import evaluate_lifecycle_evidence
+from .model import DependencyPhase, EvidenceNodeScope, EvidenceProvenance, ResolutionStatus
+from .repository.discover import discover_repository
+from .repository.snapshot import capture_snapshot, compare_snapshots
+from .review_evidence import (
+    evaluate_agent_decisions,
+    load_agent_decisions,
+    load_external_evidence,
+    merge_external_dependencies,
+)
+from .validation.components import partition_components
+from .validation.profile import find_profile, validate_profile
+from .validation.rules import evaluate_component_dependency_policy, evaluate_declared_dependency_boundaries
+
+
+def _recalculate_outcome(report: dict[str, object]) -> None:
+    diagnostics = report.get("diagnostics", [])
+    coverage = report.get("coverage", {})
+    non_conformant = any(
+        isinstance(item, dict) and item.get("outcome_effect") == "NON_CONFORMANT"
+        for item in diagnostics
+        if isinstance(diagnostics, list)
+    )
+    incomplete_diagnostic = any(
+        isinstance(item, dict) and item.get("outcome_effect") == "INCOMPLETE"
+        for item in diagnostics
+        if isinstance(diagnostics, list)
+    )
+    blocking = coverage.get("blocking_gaps", []) if isinstance(coverage, dict) else []
+    if non_conformant:
+        report["outcome"] = "NON_CONFORMANT"
+    elif incomplete_diagnostic or bool(blocking):
+        report["outcome"] = "INCOMPLETE"
+    else:
+        report["outcome"] = "CONFORMANT"
+
+
+def _externally_supplemented_native_ids(native: DependencyScan, external_edges: tuple) -> set[str]:
+    resolved_external = [
+        edge
+        for edge in external_edges
+        if edge.resolution in {ResolutionStatus.RESOLVED, ResolutionStatus.EXTERNAL}
+        and edge.target_scope != EvidenceNodeScope.UNRESOLVED_TARGET
+        and edge.provenance == EvidenceProvenance.OBSERVED
+    ]
+    supplemented: set[str] = set()
+    for native_edge in native.edges:
+        # A DYNAMIC edge has no concrete target identity by definition.  An
+        # imported document that repeats the sentinel target cannot turn that
+        # uncertainty into evidence of absence, so only native UNRESOLVED edges
+        # are eligible for strict external supplementation.
+        if native_edge.resolution != ResolutionStatus.UNRESOLVED:
+            continue
+        if any(
+            external.source == native_edge.source
+            and external.target == native_edge.target
+            and external.edge_type == native_edge.edge_type
+            and (external.phase == native_edge.phase or native_edge.phase == DependencyPhase.UNKNOWN)
+            for external in resolved_external
+        ):
+            supplemented.add(native_edge.evidence_id)
+    return supplemented
+
+
+def _external_conflict_gaps(native: DependencyScan, external_edges: tuple) -> list[dict[str, object]]:
+    gaps: list[dict[str, object]] = []
+    for external in external_edges:
+        for observed in native.edges:
+            if (
+                observed.source != external.source
+                or observed.target != external.target
+                or observed.edge_type != external.edge_type
+                or (observed.phase != external.phase and observed.phase != DependencyPhase.UNKNOWN)
+            ):
+                continue
+            if observed.resolution in {ResolutionStatus.UNRESOLVED, ResolutionStatus.DYNAMIC}:
+                continue
+            contradictory_scope = observed.target_scope != external.target_scope
+            contradictory_path = (
+                observed.resolution == ResolutionStatus.RESOLVED
+                and external.resolution == ResolutionStatus.RESOLVED
+                and observed.resolved_path != external.resolved_path
+            )
+            if not (contradictory_scope or contradictory_path):
+                continue
+            gaps.append(
+                {
+                    "id": "external-evidence:conflict:" + hashlib.sha256((observed.evidence_id + external.evidence_id).encode()).hexdigest()[:16],
+                    "blocking": True,
+                    "rule_ids": ["PTSIP-EVD-002", "PTSIP-EVD-003", "PTSIP-EVD-004"],
+                    "evidence_ids": [observed.evidence_id, external.evidence_id],
+                    "message": "Imported external dependency evidence contradicts resolved native repository evidence and therefore cannot override it silently.",
+                }
+            )
+    return gaps
+
+
+def _external_input_gaps(external_load) -> list[dict[str, object]]:
+    return [
+        {
+            "id": "external-evidence:invalid:" + hashlib.sha256((issue.source_path + issue.message).encode()).hexdigest()[:16],
+            "blocking": True,
+            "rule_ids": ["PTSIP-EVD-003", "PTSIP-EVD-004"],
+            "evidence_ids": [f"external-input:{issue.source_path}"],
+            "message": f"Explicit external evidence input is unusable for strict conformance: {issue.message}",
+        }
+        for issue in external_load.issues
+    ]
+
+
+def _coverage_without_supplemented(gaps: list[dict[str, object]], supplemented_ids: set[str]) -> list[dict[str, object]]:
+    result: list[dict[str, object]] = []
+    for gap in gaps:
+        evidence_ids = {str(item) for item in gap.get("evidence_ids", [])}
+        if str(gap.get("id", "")).startswith("dependency-target:") and evidence_ids & supplemented_ids:
+            continue
+        result.append(gap)
+    return result
+
+
+def evaluate_conformance(
+    path: str | Path = ".",
+    profile_path: str | Path | None = None,
+    artifact_evidence_paths: list[str | Path] | tuple[str | Path, ...] | None = None,
+    agent_decision_paths: list[str | Path] | tuple[str | Path, ...] | None = None,
+    external_evidence_paths: list[str | Path] | tuple[str | Path, ...] | None = None,
+) -> ConformanceResult:
+    repo = discover_repository(path)
+    root = Path(repo.root).resolve()
+    final_before = capture_snapshot(root)
+    base = evaluate_base_conformance(
+        path,
+        profile_path,
+        artifact_evidence_paths,
+        _snapshot_before=final_before,
+        _finalize_snapshot=False,
+    )
+    report = base.report
+    profile = find_profile(root, profile_path)
+    validation = validate_profile(root, profile_path)
+
+    native_dependencies = scan_dependency_edges(root)
+    external_load = load_external_evidence(external_evidence_paths, repo)
+    dependencies = merge_external_dependencies(native_dependencies, external_load)
+    report["dependencies"] = dependencies.as_dict()
+    report["external_evidence"] = external_load.as_dict()
+
+    diagnostics = list(report.get("diagnostics", [])) if isinstance(report.get("diagnostics"), list) else []
+    diagnostics = [
+        item
+        for item in diagnostics
+        if not (
+            isinstance(item, dict)
+            and isinstance(item.get("evaluator"), dict)
+            and item["evaluator"].get("id") == "declared-dependency-boundaries"
+        )
+    ]
+    coverage = report.get("coverage")
+    if not isinstance(coverage, dict):
+        coverage = {"blocking_gaps": [], "non_blocking_gaps": []}
+        report["coverage"] = coverage
+    blocking = list(coverage.get("blocking_gaps", [])) if isinstance(coverage.get("blocking_gaps"), list) else []
+    non_blocking = list(coverage.get("non_blocking_gaps", [])) if isinstance(coverage.get("non_blocking_gaps"), list) else []
+    replace_prefixes = (
+        "dependency-scan:",
+        "dependency-target:",
+        "component-ownership:",
+        "build-resolution:coverage",
+        "build-resolution:",
+        "lifecycle:",
+        "language-coverage:",
+        "agent-decision:",
+        "external-evidence:",
+        "conformance-audit:",
+    )
+    blocking = [item for item in blocking if not (isinstance(item, dict) and str(item.get("id", "")).startswith(replace_prefixes))]
+    non_blocking = [item for item in non_blocking if not (isinstance(item, dict) and str(item.get("id", "")).startswith(replace_prefixes))]
+
+    evaluators = report.get("evaluators")
+    if not isinstance(evaluators, dict):
+        evaluators = {}
+        report["evaluators"] = evaluators
+    evaluators["external_evidence_import"] = {
+        "status": "NOT_APPLICABLE" if not external_evidence_paths else ("BLOCKED" if external_load.issues else "RAN"),
+        "reason": None if not external_load.issues else "EXTERNAL_EVIDENCE_INVALID_OR_STALE",
+        "document_count": len(external_load.documents),
+        "edge_count": len(external_load.edges),
+    }
+    blocking.extend(_external_input_gaps(external_load))
+    blocking.extend(_external_conflict_gaps(native_dependencies, external_load.edges))
+
+    components: list[dict[str, object]] = []
+    payload: dict[str, object] | None = None
+    if profile is not None and validation.valid:
+        loaded = yaml.safe_load(profile.read_text(encoding="utf-8-sig"))
+        payload = loaded if isinstance(loaded, dict) else None
+        declared = payload.get("components") if payload is not None else None
+        if isinstance(declared, list):
+            components = [item for item in declared if isinstance(item, dict)]
+
+    agent_load = load_agent_decisions(agent_decision_paths)
+    agent_report, agent_gaps = evaluate_agent_decisions(agent_load, components)
+    report["agent_decisions"] = agent_report
+    blocking.extend(agent_gaps)
+    evaluators["agent_decision_review"] = {
+        "status": "NOT_APPLICABLE" if not agent_decision_paths else ("BLOCKED" if agent_load.issues else "RAN"),
+        "reason": None if not agent_load.issues else "AGENT_DECISION_INPUT_INVALID",
+        "document_count": len(agent_load.documents),
+    }
+
+    if components:
+        partition = partition_components(root, components)
+        boundary_findings = evaluate_declared_dependency_boundaries(components, partition, dependencies)
+        diagnostics.extend(_finding_diagnostic(item, "declared-dependency-boundaries") for item in boundary_findings)
+        dependency_gaps = _dependency_coverage_gaps(dependencies, components, partition)
+        supplemented = _externally_supplemented_native_ids(native_dependencies, external_load.edges)
+        dependency_gaps = _coverage_without_supplemented(dependency_gaps, supplemented)
+        blocking.extend(item for item in dependency_gaps if item.get("blocking"))
+        non_blocking.extend(item for item in dependency_gaps if not item.get("blocking"))
+        ownership_gaps = _unassigned_coverage_gaps(partition)
+        blocking.extend(item for item in ownership_gaps if item.get("blocking"))
+        non_blocking.extend(item for item in ownership_gaps if not item.get("blocking"))
+        language_gaps = _unsupported_source_coverage_gaps(partition, components)
+        blocking.extend(language_gaps)
+        evaluators["source_language_coverage"] = {
+            "status": "BLOCKED" if language_gaps else "RAN",
+            "reason": "UNSUPPORTED_MANDATORY_SOURCE" if language_gaps else None,
+            "supported_suffixes": sorted(SUPPORTED_SOURCE_SUFFIXES),
+            "unsupported_source_count": sum(len(item.get("evidence_ids", [])) for item in language_gaps),
+        }
+        evaluators["declared_dependency_boundaries"] = {
+            "status": "RAN",
+            "reason": None,
+            "finding_count": len(boundary_findings),
+        }
+
+        component_policy = payload.get("component_dependency_policy") if payload is not None else None
+        policy_results = evaluate_component_dependency_policy(
+            component_policy if isinstance(component_policy, dict) else None,
+            components,
+            partition,
+            dependencies,
+        )
+        report["project_policy"] = {
+            "findings": [item.as_dict() for item in policy_results],
+            "finding_count": len(policy_results),
+            "affects_ptsip_outcome": False,
+        }
+        evaluators["component_dependency_policy"] = {
+            "status": "RAN" if isinstance(component_policy, dict) else "NOT_APPLICABLE",
+            "reason": None,
+            "finding_count": len(policy_results),
+        }
+
+        build = evaluate_independent_build_resolution(root, components, partition)
+        evaluators["independent_build_resolution"] = {
+            "status": build.status,
+            "reason": build.reason,
+            "manifest_count": len(build.manifests),
+        }
+        blocking.extend(build.blocking_gaps)
+        report["build_resolution"] = build.as_dict()
+
+        lifecycle = evaluate_lifecycle_evidence(root, components, partition)
+        evaluators["lifecycle_independence"] = {
+            "status": lifecycle.status,
+            "reason": lifecycle.reason,
+            "release_workflow_count": len(lifecycle.workflows),
+        }
+        blocking.extend(lifecycle.blocking_gaps)
+        report["lifecycle"] = lifecycle.as_dict()
+    else:
+        evaluators["source_language_coverage"] = {"status": "BLOCKED", "reason": "COMPONENT_DECLARATIONS_REQUIRED"}
+        evaluators["independent_build_resolution"] = {"status": "BLOCKED", "reason": "COMPONENT_DECLARATIONS_REQUIRED"}
+        evaluators["lifecycle_independence"] = {"status": "BLOCKED", "reason": "COMPONENT_DECLARATIONS_REQUIRED"}
+        report["build_resolution"] = {
+            "status": "BLOCKED",
+            "reason": "COMPONENT_DECLARATIONS_REQUIRED",
+            "manifests": [],
+            "blocking_gaps": [],
+        }
+        report["lifecycle"] = {
+            "status": "BLOCKED",
+            "reason": "COMPONENT_DECLARATIONS_REQUIRED",
+            "workflows": [],
+            "blocking_gaps": [],
+            "observations": [],
+        }
+
+    report["diagnostics"] = diagnostics
+    coverage["blocking_gaps"] = blocking
+    coverage["non_blocking_gaps"] = non_blocking
+    profile_report = report.get("profile", {})
+    profile_valid = isinstance(profile_report, dict) and profile_report.get("valid") is True
+    specification = report.get("specification", {})
+    spec_bound = isinstance(specification, dict) and bool(specification.get("revision"))
+    artifact_documents = report.get("artifacts", {}).get("documents", []) if isinstance(report.get("artifacts"), dict) else []
+    artifact_bound = bool(artifact_documents) and all(
+        isinstance(item, dict) and item.get("binding_valid") is True for item in artifact_documents
+    )
+    evaluators["profile_validation"] = {
+        "status": "RAN" if profile_valid else "BLOCKED",
+        "reason": None if profile_valid else "PROFILE_INVALID",
+    }
+    evaluators["specification_revision_binding"] = {
+        "status": "RAN" if profile_valid and spec_bound else "BLOCKED",
+        "reason": None if profile_valid and spec_bound else "IMMUTABLE_SPECIFICATION_BINDING_REQUIRED",
+    }
+    evaluators["artifact_snapshot_binding"] = {
+        "status": "RAN" if artifact_bound else "BLOCKED",
+        "reason": None if artifact_bound else "ARTIFACT_REVISION_BINDING_REQUIRED",
+        "document_count": len(artifact_documents),
+    }
+    coverage["applicability"] = {
+        "profile_and_specification": {"applicable": True, "status": "SUFFICIENT" if profile_valid and spec_bound else "INSUFFICIENT"},
+        "dependency_boundaries": {"applicable": True, "status": "SUFFICIENT" if evaluators.get("declared_dependency_boundaries", {}).get("status") == "RAN" else "INSUFFICIENT"},
+        "source_language_coverage": {"applicable": True, "status": "SUFFICIENT" if evaluators["source_language_coverage"]["status"] == "RAN" else "INSUFFICIENT"},
+        "product_artifact_boundary": {"applicable": True, "status": "SUFFICIENT" if evaluators.get("product_artifact_boundary", {}).get("status") == "RAN" and artifact_bound else "INSUFFICIENT"},
+        "independent_build_resolution": {"applicable": True, "status": "SUFFICIENT" if evaluators.get("independent_build_resolution", {}).get("status") == "RAN" else "INSUFFICIENT"},
+        "lifecycle_independence": {"applicable": True, "status": "SUFFICIENT" if evaluators.get("lifecycle_independence", {}).get("status") == "RAN" else "INSUFFICIENT"},
+    }
+    _recalculate_outcome(report)
+
+    # Run the semantic audit inside the observation envelope before the final
+    # repository snapshot.  A final pure report audit below validates the
+    # snapshot result itself without collecting additional repository evidence.
+    audit_conformance_report(report)
+    final_after = capture_snapshot(root)
+    final_comparison = compare_snapshots(final_before, final_after)
+    report["snapshot"] = {
+        "before": final_before.as_dict(),
+        "after": final_after.as_dict(),
+        "comparison": final_comparison.as_dict(),
+    }
+    if not final_comparison.stable and not any(
+        isinstance(item, dict) and item.get("id") == "snapshot:invalidated"
+        for item in coverage["blocking_gaps"]
+    ):
+        coverage["blocking_gaps"].append(
+            {
+                "id": "snapshot:invalidated",
+                "blocking": True,
+                "rule_ids": ["PTSIP-EVD-001", "PTSIP-EVD-003"],
+                "evidence_ids": ["snapshot:comparison"],
+                "message": "Repository evidence changed or was incomplete during the complete enforced conformance evaluation.",
+            }
+        )
+    evaluators["snapshot_integrity"] = {
+        "status": "RAN" if final_comparison.stable else "BLOCKED",
+        "reason": None if final_comparison.stable else "EVALUATION_SNAPSHOT_INVALIDATED",
+    }
+    coverage["applicability"]["snapshot_integrity"] = {
+        "applicable": True,
+        "status": "SUFFICIENT" if final_comparison.stable else "INSUFFICIENT",
+    }
+    _recalculate_outcome(report)
+
+    audit = audit_conformance_report(report)
+    report["audit"] = audit
+    evaluators["conformance_report_audit"] = {
+        "status": "RAN" if audit["status"] == "PASS" else "BLOCKED",
+        "reason": None if audit["status"] == "PASS" else "REPORT_CONTRACT_AUDIT_FAILED",
+        "problem_count": audit["problem_count"],
+    }
+    if audit["status"] != "PASS":
+        coverage["blocking_gaps"].append(
+            {
+                "id": "conformance-audit:report-contract",
+                "blocking": True,
+                "rule_ids": ["PTSIP-DIA-001", "PTSIP-EVD-003"],
+                "evidence_ids": ["conformance-audit:report-contract"],
+                "message": "Internal conformance report contract audit failed: " + "; ".join(str(item) for item in audit["problems"][:10]),
+            }
+        )
+        _recalculate_outcome(report)
+    return ConformanceResult(report=report)

ptsip/constants.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+TOOL_NAME = "PTSIP Tool"
+TOOL_VERSION = "0.3.1"
+SPEC_NAME = "Product–Toolchain SDK Isolation Policy"
+SPEC_ACRONYM = "PTSIP"
+SPEC_VERSION = "0.2.0-draft"
+SPEC_SOURCE = "https://github.com/kwaksinwoo01/ptsip"
+SPEC_REVISION = "a877b2f66a7f94c1b844c979e1b08fb08a9a8e45"

ptsip/doctor.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+from .storage.local_state import ptsip_home
+
+
+def doctor(path: str | Path = ".") -> dict[str, object]:
+    target = Path(path).expanduser().resolve()
+    current_minor = (sys.version_info.major, sys.version_info.minor)
+    metadata_supported = current_minor >= (3, 11)
+    ci_verified = (3, 11) <= current_minor <= (3, 14)
+    github_cli = shutil.which("gh")
+    return {
+        "python": sys.version.split()[0],
+        "python_ok": metadata_supported,
+        "python_supported_by_metadata": metadata_supported,
+        "python_ci_verified": ci_verified,
+        "python_ci_verified_range": "3.11-3.14",
+        "python_support_note": (
+            "This interpreter is within the current CI-verified range."
+            if ci_verified
+            else "Package metadata allows this interpreter, but this minor version is outside the current CI matrix."
+        ),
+        "git": shutil.which("git"),
+        "github_cli": github_cli,
+        "github_issue_publish_available": github_cli is not None,
+        "target": str(target),
+        "target_exists": target.exists(),
+        "ptsip_home": str(ptsip_home()),
+    }

ptsip/inspection/__init__.py

@@ -0,0 +1 @@
+"""Read-only repository inspection."""

ptsip/inspection/components.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from ..model import DecisionStatus
+from .dependencies import DependencyScan
+from .inventory import Inventory
+
+
+@dataclass(frozen=True)
+class ComponentCandidate:
+    id: str
+    include: tuple[str, ...]
+    anchors: tuple[str, ...]
+    evidence_ids: tuple[str, ...]
+    decision_status: DecisionStatus = DecisionStatus.UNKNOWN
+    classification: None = None
+
+    def as_dict(self) -> dict[str, object]:
+        payload = asdict(self)
+        payload["decision_status"] = self.decision_status.value
+        return payload
+
+
+def _slug(value: str) -> str:
+    text = re.sub(r"[^a-zA-Z0-9]+", "-", value).strip("-").lower()
+    return text or "repository-root"
+
+
+def discover_component_candidates(root: str | Path, inventory: Inventory, dependencies: DependencyScan) -> list[ComponentCandidate]:
+    root = Path(root).resolve()
+    raw: dict[str, dict[str, set[str]]] = {}
+
+    def add(selector: str, anchor: str, evidence_id: str) -> None:
+        item = raw.setdefault(selector, {"anchors": set(), "evidence_ids": set()})
+        item["anchors"].add(anchor)
+        item["evidence_ids"].add(evidence_id)
+
+    for manifest in inventory.manifests:
+        parent = Path(manifest).parent.as_posix()
+        selector = manifest if parent in {".", ""} else f"{parent}/**"
+        add(selector, "manifest", f"manifest:{manifest}")
+
+    schema_parents: dict[str, int] = {}
+    for schema in inventory.schema_candidates:
+        parent = Path(schema).parent.as_posix()
+        schema_parents[parent] = schema_parents.get(parent, 0) + 1
+    for parent, count in schema_parents.items():
+        selector = f"{parent}/**" if parent not in {".", ""} else "*.schema.*"
+        add(selector, "contract/schema-group", f"schema-group:{parent}:{count}")
+
+    for name in inventory.tool_like_roots:
+        add(f"{name}/**", "top-level-tool-root", f"root:{name}")
+    for name in inventory.test_roots:
+        add(f"{name}/**", "top-level-test-root", f"root:{name}")
+
+    for edge in dependencies.edges:
+        if edge.adapter == "github-actions" and edge.resolved_path:
+            add(edge.resolved_path, "ci-invoked-script", edge.evidence_id)
+
+    candidates: list[ComponentCandidate] = []
+    for selector, details in sorted(raw.items()):
+        selector_path = selector.removesuffix("/**")
+        candidates.append(
+            ComponentCandidate(
+                id=_slug(selector_path),
+                include=(selector,),
+                anchors=tuple(sorted(details["anchors"])),
+                evidence_ids=tuple(sorted(details["evidence_ids"])),
+            )
+        )
+    return candidates