pgc-compiler 2.0.0__py3-none-any.whl

compiler/atoms/phase.py

@@ -0,0 +1,99 @@
+"""
+Phase result model for pipeline execution.
+
+Design:
+- Explicit status (SUCCESS/PARTIAL/FAILED)
+- Typed outputs (phase-specific data)
+- Error collection (all errors, not just first)
+- Metrics (timing, counts for reporting)
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from compiler.atoms.errors import CompilerError
+
+
+class PhaseStatus(Enum):
+    """Phase execution status."""
+
+    SUCCESS = "SUCCESS"  # No errors, all items processed
+    PARTIAL = "PARTIAL"  # Some errors, some items processed
+    FAILED = "FAILED"  # Critical error, phase could not complete
+
+
+@dataclass
+class PhaseMetrics:
+    """
+    Metrics for phase execution.
+
+    Used for reporting and performance analysis.
+    """
+
+    duration_ms: int = 0
+    items_processed: int = 0
+    items_failed: int = 0
+    items_skipped: int = 0
+
+    def __post_init__(self) -> None:
+        """Calculate total."""
+        self.total = self.items_processed + self.items_failed + self.items_skipped
+
+
+@dataclass(frozen=True)
+class PhaseResult:
+    """
+    Result from phase execution.
+
+    All phases return this type for consistency.
+
+    IMMUTABILITY GUARANTEE:
+    - frozen=True prevents mutation after creation
+    - No phase side-effects
+    - No hidden mutation across pipeline
+    - Build once with all errors, don't mutate
+
+    Fields:
+        status: Execution status
+        outputs: Phase-specific output data (artifacts, metadata, etc.)
+        errors: Tuple of errors encountered (immutable)
+        metrics: Performance metrics
+
+    Examples:
+        >>> result = PhaseResult(
+        ...     status=PhaseStatus.SUCCESS,
+        ...     outputs={"artifacts": [...]},
+        ...     errors=(),
+        ...     metrics=PhaseMetrics(duration_ms=50, items_processed=10)
+        ... )
+    """
+
+    status: PhaseStatus
+    outputs: dict[str, Any]
+    errors: tuple[CompilerError, ...] = field(default_factory=tuple)
+    metrics: PhaseMetrics = field(default_factory=PhaseMetrics)
+
+    @property
+    def success(self) -> bool:
+        """Check if phase succeeded (no errors)."""
+        return self.status == PhaseStatus.SUCCESS and len(self.errors) == 0
+
+    @property
+    def failed(self) -> bool:
+        """Check if phase failed (critical error or all items failed)."""
+        return self.status == PhaseStatus.FAILED
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON output."""
+        return {
+            "status": self.status.value,
+            "outputs": self.outputs,
+            "errors": [e.to_dict() for e in self.errors],
+            "metrics": {
+                "duration_ms": self.metrics.duration_ms,
+                "items_processed": self.metrics.items_processed,
+                "items_failed": self.metrics.items_failed,
+                "items_skipped": self.metrics.items_skipped,
+            },
+        }

compiler/atoms/pipeline.py

@@ -0,0 +1,51 @@
+"""
+pipeline.py — Compiler pipeline metadata management.
+
+Defines which fields are transient compiler-operational state and must never
+cross the materialization boundary into compiled artifacts or snapshots.
+
+Design principle:
+  Compiled artifacts must contain ONLY governable semantic state.
+  They must never contain:
+    - local filesystem state  (source_path, loader_origin)
+    - compiler operational state  (parse_cache, temp_resolution)
+    - author workstation state  (filesystem hints, debug fields)
+    - build-environment leakage  (absolute paths, host identifiers)
+
+  Transient fields serve the build pipeline internally (e.g., discover → parse)
+  and are stripped at the materialization boundary — the formal threshold between
+  compiler-operational state and protocol-semantic state.
+
+  As new pipeline-internal fields are introduced, register them here.
+  Never use ad hoc .pop() at call sites.
+"""
+
+# Fields that are compiler-internal pipeline metadata.
+# Present on artifact dicts during build; must not appear in materialized output.
+_TRANSIENT_PIPELINE_FIELDS: frozenset[str] = frozenset(
+    {
+        "source_path",      # Absolute filesystem path set by discover; used by parse to load content
+        # Future candidates (register here as needed):
+        # "parse_cache",
+        # "loader_origin",
+        # "compiler_debug",
+        # "temp_resolution",
+        # "filesystem_hint",
+    }
+)
+
+
+def strip_transient_pipeline_fields(artifact: dict) -> dict:
+    """
+    Return a copy of artifact with all transient compiler pipeline fields removed.
+
+    Call this once, immediately before serializing an artifact to disk.
+    The returned dict is a shallow copy — nested structures are not copied.
+
+    Args:
+        artifact: Artifact dict as it exists in the compiler pipeline.
+
+    Returns:
+        New dict with transient fields stripped. Original is not mutated.
+    """
+    return {k: v for k, v in artifact.items() if k not in _TRANSIENT_PIPELINE_FIELDS}

compiler/atoms/snapshot_gate.py

@@ -0,0 +1,51 @@
+"""
+Snapshot admission control gate.
+
+All CLI subcommands that consume a compiled workspace snapshot
+MUST call assert_snapshot_valid() before reading from it.
+
+The admissibility chain:
+  Invalid Protocol → No Snapshot → Invalid Snapshot → No Build → Invalid Build → No Index
+"""
+
+import json
+import sys
+from pathlib import Path
+
+
+def assert_snapshot_valid(workspace: Path) -> None:
+    """
+    Hard gate: workspace snapshot must be VALID before any consumer subcommand proceeds.
+
+    Reads snapshot_status.json from the workspace root. Exits 1 with a diagnostic
+    message if the file is missing, unreadable, or reports a non-VALID status.
+
+    Args:
+        workspace: Absolute path to pgs_workspace root.
+
+    Raises:
+        SystemExit(1): If snapshot is absent or not VALID.
+    """
+    snapshot_status_file = workspace / "snapshot_status.json"
+
+    if not snapshot_status_file.exists():
+        print(
+            "ERROR: snapshot_status.json not found — snapshot has not been built.\n"
+            "       Run 'compiler build --workspace <path>' first.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    try:
+        snapshot_status = json.loads(snapshot_status_file.read_text())
+    except Exception as exc:
+        print(f"ERROR: Failed to read snapshot_status.json: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if snapshot_status.get("status") != "VALID":
+        print(
+            f"ERROR: Snapshot is not VALID (status: {snapshot_status.get('status', 'UNKNOWN')}).\n"
+            "       Fix all compile errors and rebuild the snapshot before proceeding.",
+            file=sys.stderr,
+        )
+        sys.exit(1)

compiler/atoms/sorting.py

@@ -0,0 +1,125 @@
+"""
+Deterministic sorting utilities.
+
+Design:
+- Sort by FQDN (primary identity)
+- Stable ordering (same input → same order)
+- No implicit ordering (dict iteration, set ordering)
+- Explicit sort at phase boundaries
+"""
+
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+def sort_artifacts_by_fqdn(artifacts: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """
+    Sort artifacts by FQDN (deterministic ordering).
+
+    CRITICAL: Use this at phase boundaries to prevent nondeterminism.
+
+    Args:
+        artifacts: List of artifact dicts (must have "fqdn_id" field)
+
+    Returns:
+        Sorted list (by fqdn_id lexicographic order)
+
+    Examples:
+        >>> artifacts = [
+        ...     {"fqdn_id": "pkg_b::CT_FOO_V0", ...},
+        ...     {"fqdn_id": "pkg_a::CT_BAR_V0", ...},
+        ... ]
+        >>> sorted_artifacts = sort_artifacts_by_fqdn(artifacts)
+        >>> [a["fqdn_id"] for a in sorted_artifacts]
+        ['pkg_a::CT_BAR_V0', 'pkg_b::CT_FOO_V0']
+    """
+    return sorted(artifacts, key=lambda a: a["fqdn_id"])
+
+
+def sort_by_fqdn(items: list[T], key_func: Callable[[T], str]) -> list[T]:
+    """
+    Sort generic items by FQDN key (deterministic ordering).
+
+    More flexible version - works with any type.
+
+    Args:
+        items: List of items to sort
+        key_func: Function to extract FQDN string from item
+
+    Returns:
+        Sorted list (by FQDN lexicographic order)
+
+    Examples:
+        >>> from dataclasses import dataclass
+        >>> @dataclass
+        ... class Artifact:
+        ...     fqdn: str
+        ...     data: dict
+        >>> artifacts = [
+        ...     Artifact("pkg_b::CT_FOO_V0", {}),
+        ...     Artifact("pkg_a::CT_BAR_V0", {}),
+        ... ]
+        >>> sorted_artifacts = sort_by_fqdn(artifacts, lambda a: a.fqdn)
+        >>> [a.fqdn for a in sorted_artifacts]
+        ['pkg_a::CT_BAR_V0', 'pkg_b::CT_FOO_V0']
+    """
+    return sorted(items, key=key_func)
+
+
+def sort_dict_keys(d: dict[str, Any]) -> dict[str, Any]:
+    """
+    Sort dictionary by keys (deterministic ordering).
+
+    Use for JSON output to ensure byte-identical outputs.
+
+    Args:
+        d: Dictionary to sort
+
+    Returns:
+        New dict with keys in lexicographic order
+
+    Examples:
+        >>> d = {"z": 1, "a": 2, "m": 3}
+        >>> sorted_d = sort_dict_keys(d)
+        >>> list(sorted_d.keys())
+        ['a', 'm', 'z']
+    """
+    return dict(sorted(d.items()))
+
+
+def ensure_deterministic_output(obj: Any) -> Any:
+    """
+    Recursively sort all collections for deterministic output.
+
+    Use before JSON serialization to guarantee byte-identical outputs.
+
+    Args:
+        obj: Object to make deterministic (dict, list, primitive)
+
+    Returns:
+        Deterministic version (sorted dicts, sorted lists where applicable)
+
+    Examples:
+        >>> obj = {
+        ...     "artifacts": [
+        ...         {"fqdn_id": "b::CT", "name": "foo"},
+        ...         {"fqdn_id": "a::CT", "name": "bar"},
+        ...     ],
+        ...     "z_field": "last",
+        ...     "a_field": "first",
+        ... }
+        >>> deterministic = ensure_deterministic_output(obj)
+        >>> list(deterministic.keys())
+        ['a_field', 'artifacts', 'z_field']
+    """
+    if isinstance(obj, dict):
+        # Sort dict keys and recursively process values
+        return {k: ensure_deterministic_output(v) for k, v in sorted(obj.items())}
+    elif isinstance(obj, list):
+        # Recursively process list items
+        # Don't sort lists (order may be meaningful)
+        return [ensure_deterministic_output(item) for item in obj]
+    else:
+        # Primitives (str, int, bool, None) pass through
+        return obj