@structupath/pi-steel 0.2.2 → 0.2.3

package/skills/_shared/pi_steel/cli.py

@@ -0,0 +1,167 @@
+"""Shared command-line behavior for shipped pi-steel stages."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .run_manifest import (
+    ManifestError,
+    RunPublisher,
+    canonical_json_bytes,
+    sha256_bytes,
+    sha256_file,
+)
+
+
+class StageArgumentParser(argparse.ArgumentParser):
+    """Map command usage errors to the shared stage-contract exit code."""
+
+    def configure_failure_diagnostics(
+        self,
+        *,
+        stage: str,
+        entry_file: str,
+        input_option: str,
+        date_options: dict[str, str] | None = None,
+    ) -> None:
+        self._failure_context = {
+            "stage": stage,
+            "entry_file": entry_file,
+            "input_option": input_option,
+            "date_options": date_options or {},
+        }
+
+    def parse_args(self, args=None, namespace=None):
+        self._active_argv = list(sys.argv[1:] if args is None else args)
+        return super().parse_args(args, namespace)
+
+    def _option_value(self, option: str) -> str | None:
+        argv = getattr(self, "_active_argv", [])
+        for index, argument in enumerate(argv):
+            if argument == option and index + 1 < len(argv):
+                return str(argv[index + 1])
+            if str(argument).startswith(f"{option}="):
+                return str(argument).split("=", 1)[1]
+        action = next(
+            (item for item in self._actions if option in item.option_strings),
+            None,
+        )
+        if action is not None and action.default not in (None, argparse.SUPPRESS):
+            return str(action.default)
+        return None
+
+    def error(self, message):
+        diagnostic_path = None
+        context = getattr(self, "_failure_context", None)
+        if context is not None:
+            destination = self._option_value("--out")
+            if destination is not None:
+                explicit_dates = {
+                    field: value
+                    for option, field in context["date_options"].items()
+                    if (value := self._option_value(option)) is not None
+                }
+                diagnostic_path = publish_failure_diagnostic(
+                    destination,
+                    stage=context["stage"],
+                    input_path=self._option_value(context["input_option"]),
+                    error=ValueError(message),
+                    tool_version=package_version(context["entry_file"]),
+                    run_id=self._option_value("--run-id"),
+                    explicit_dates=explicit_dates,
+                    finding_code="cli_usage_error",
+                )
+        self.print_usage(sys.stderr)
+        suffix = (
+            f"; diagnostic published: {diagnostic_path}"
+            if diagnostic_path is not None
+            else ""
+        )
+        self.exit(1, f"{self.prog}: error: {message}{suffix}\n")
+
+
+def package_version(entry_file: str) -> str:
+    package_path = Path(entry_file).resolve().parents[3] / "package.json"
+    try:
+        return json.loads(package_path.read_text(encoding="utf-8"))["version"]
+    except (OSError, KeyError, json.JSONDecodeError):
+        return "unknown"
+
+
+def _diagnostic_message(error: Exception) -> str:
+    """Describe a failure without persisting input paths in published artifacts."""
+    if isinstance(error, OSError):
+        detail = error.strerror or "input/output error"
+        return f"{error.__class__.__name__}: {detail}"
+    return str(error) or error.__class__.__name__
+
+
+def publish_failure_diagnostic(
+    destination: str | Path,
+    *,
+    stage: str,
+    input_path: str | Path | None,
+    error: Exception,
+    tool_version: str,
+    run_id: str | None = None,
+    explicit_dates: dict[str, str] | None = None,
+    finding_code: str = "input_unreadable_or_invalid",
+) -> Path | None:
+    """Best-effort publication for failures that occur after CLI parsing.
+
+    The original failure remains authoritative: publication errors are contained so
+    callers can preserve the shared exit-code contract and report the first error.
+    """
+    path = Path(input_path) if input_path is not None else None
+    try:
+        input_hash = (
+            sha256_file(path)
+            if path is not None and path.is_file()
+            else sha256_bytes(canonical_json_bytes({"input_state": "unavailable"}))
+        )
+        message = _diagnostic_message(error)
+        finding: dict[str, Any] = {
+            "code": finding_code,
+            "severity": "error",
+            "message": message,
+            "exception_type": error.__class__.__name__,
+        }
+        qa_report = {
+            "schema_version": "1.0.0",
+            "stage": stage,
+            "run_outcome": "usage_or_internal_error",
+            "package_status": "draft",
+            "findings": [finding],
+            "warnings": [],
+        }
+        configuration_hash = sha256_bytes(
+            canonical_json_bytes(
+                {
+                    "failure_contract": "1.0.0",
+                    "stage": stage,
+                    "explicit_dates": explicit_dates or {},
+                }
+            )
+        )
+        with RunPublisher(
+            destination,
+            stage=stage,
+            run_outcome="usage_or_internal_error",
+            package_status="draft",
+            input_hash=input_hash,
+            configuration_hash=configuration_hash,
+            schema_versions={"run_manifest": "1.0.0"},
+            tool_versions={"pi_steel": tool_version},
+            explicit_dates=explicit_dates or {},
+            warnings=[message],
+            approximations=[],
+            run_id=run_id,
+        ) as publisher:
+            publisher.write_qa_report(qa_report)
+            return publisher.publish()
+    except (ManifestError, OSError, TypeError, ValueError):
+        return None

package/skills/_shared/pi_steel/contracts.py

@@ -0,0 +1,87 @@
+"""Canonical contract constants and deterministic identity helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+ESTIMATE_PACKAGE_VERSION = "1.0.0"
+NEST_RESULT_VERSION = "1.0.0"
+ITEM_INTENTS = frozenset(
+    {
+        "fabricated_part",
+        "purchased_stock",
+        "hardware",
+        "allowance",
+        "exclusion",
+        "by_others",
+    }
+)
+
+
+def canonical_json_bytes(value: Any) -> bytes:
+    return json.dumps(
+        value, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+
+
+def content_hash(value: Any) -> str:
+    return hashlib.sha256(canonical_json_bytes(value)).hexdigest()
+
+
+def item_id_for(project_id: str, revision_id: str, source_id: str) -> str:
+    """Derive normalized identity from project and stable source identity.
+
+    ``revision_id`` remains in the signature for adapter compatibility. Legacy
+    source IDs already embed their revision when no stable source key exists;
+    explicit source IDs therefore remain stable across revisions.
+    """
+    digest = content_hash(
+        {
+            "project_id": project_id,
+            "source_id": source_id,
+        }
+    )
+    return f"item:{digest[:24]}"
+
+
+def instance_ids(item_id: str, quantity: int) -> list[str]:
+    """Expand quantity predictably; increasing quantity never renames old instances."""
+    if quantity < 0:
+        raise ValueError("quantity must be non-negative")
+    return [f"{item_id}:instance:{index:04d}" for index in range(1, quantity + 1)]
+
+
+def placement_ids(item_id: str, quantity: int) -> list[str]:
+    """Derive stable per-instance placement identities from canonical item order."""
+    if quantity < 0:
+        raise ValueError("quantity must be non-negative")
+    return [f"{item_id}:placement:{index:04d}" for index in range(1, quantity + 1)]
+
+
+def fallback_source_id(revision_id: str, identity: Any) -> str:
+    """Create a revision-scoped legacy identity from stable row content."""
+    return f"legacy:{revision_id}:{content_hash(identity)[:20]}"
+
+
+def estimate_input_projection(package: dict[str, Any]) -> dict[str, Any]:
+    """Return source/config semantics, excluding review and confirmation bookkeeping."""
+    projection = {
+        key: value
+        for key, value in package.items()
+        if key not in {"review"}
+    }
+    projection = json.loads(json.dumps(projection))
+    for stock in projection.get("stock", []):
+        stock.pop("reviewer_confirmation", None)
+    return projection
+
+
+def estimate_input_hash(package: dict[str, Any]) -> str:
+    return content_hash(estimate_input_projection(package))
+
+
+def finding_id_for(code: str, path: str) -> str:
+    return f"finding:{content_hash({'code': code, 'path': path})[:24]}"

package/skills/_shared/pi_steel/geometry_verify.py

@@ -0,0 +1,243 @@
+"""Geometry checks shared by contract validation and nesting."""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from typing import Any
+
+
+SUPPORTED_SHAPES = frozenset({"rect", "irregular"})
+
+
+def finite_positive(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) and value > 0
+
+
+def hole_area(hole: dict[str, Any]) -> float:
+    if hole.get("kind") == "round":
+        diameter = hole.get("diameter", 0)
+        return math.pi * (diameter / 2) ** 2
+    if hole.get("kind") == "rect":
+        return hole.get("width", 0) * hole.get("height", 0)
+    return 0
+
+
+def hole_within_bounds(hole: dict[str, Any], width: float, height: float) -> bool:
+    x, y = hole.get("x"), hole.get("y")
+    if not all(isinstance(value, (int, float)) and math.isfinite(value) for value in (x, y)):
+        return False
+    if hole.get("kind") == "round":
+        diameter = hole.get("diameter")
+        if not finite_positive(diameter):
+            return False
+        radius = diameter / 2
+        return radius <= x <= width - radius and radius <= y <= height - radius
+    if hole.get("kind") == "rect":
+        hole_width, hole_height = hole.get("width"), hole.get("height")
+        if not finite_positive(hole_width) or not finite_positive(hole_height):
+            return False
+        return (
+            hole_width / 2 <= x <= width - hole_width / 2
+            and hole_height / 2 <= y <= height - hole_height / 2
+        )
+    return False
+
+
+def gross_area(geometry: dict[str, Any]) -> float:
+    if geometry.get("shape") == "irregular" and geometry.get("area") is not None:
+        return geometry["area"]
+    return geometry.get("width", 0) * geometry.get("height", 0)
+
+
+def net_area(geometry: dict[str, Any]) -> float:
+    return gross_area(geometry) - sum(hole_area(hole) for hole in geometry.get("holes", []))
+
+
+def plate_group_key(item: dict[str, Any]) -> tuple[Any, Any, Any]:
+    geometry = item.get("geometry", {})
+    return item.get("material"), item.get("grade"), geometry.get("thickness")
+
+
+def group_plate_items(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Partition parts strictly by material, grade, and thickness."""
+    groups: dict[tuple[Any, Any, Any], list[dict[str, Any]]] = defaultdict(list)
+    for item in items:
+        groups[plate_group_key(item)].append(item)
+    return [
+        {
+            "material": key[0],
+            "grade": key[1],
+            "thickness": key[2],
+            "items": grouped,
+        }
+        for key, grouped in sorted(groups.items(), key=lambda pair: repr(pair[0]))
+    ]
+
+
+def _finite_placement_values(placement: dict[str, Any]) -> bool:
+    return all(
+        isinstance(placement.get(field), (int, float))
+        and math.isfinite(placement[field])
+        for field in ("x", "y", "w", "h")
+    )
+
+
+def _placements_separated(
+    first: dict[str, Any],
+    second: dict[str, Any],
+    clearance: float,
+    epsilon: float,
+) -> bool:
+    return (
+        first["x"] + first["w"] + clearance <= second["x"] + epsilon
+        or second["x"] + second["w"] + clearance <= first["x"] + epsilon
+        or first["y"] + first["h"] + clearance <= second["y"] + epsilon
+        or second["y"] + second["h"] + clearance <= first["y"] + epsilon
+    )
+
+
+def _overlap_candidate_pairs(
+    placements: list[dict[str, Any]],
+    clearance: float,
+    epsilon: float,
+) -> list[tuple[int, int]]:
+    """Return deterministic overlap pairs without scanning every valid pair."""
+    numeric = {
+        index for index, placement in enumerate(placements)
+        if _finite_placement_values(placement)
+    }
+    sweepable = {
+        index for index in numeric
+        if placements[index]["w"] > 0 and placements[index]["h"] > 0
+    }
+    candidates: set[tuple[int, int]] = set()
+    active: list[int] = []
+    for current_index in sorted(
+        sweepable, key=lambda index: (placements[index]["x"], index)
+    ):
+        current = placements[current_index]
+        active = [
+            index
+            for index in active
+            if (
+                placements[index]["x"]
+                + placements[index]["w"]
+                + clearance
+                > current["x"] + epsilon
+            )
+        ]
+        for other_index in active:
+            other = placements[other_index]
+            if not (
+                other["y"] + other["h"] + clearance <= current["y"] + epsilon
+                or current["y"] + current["h"] + clearance
+                <= other["y"] + epsilon
+            ):
+                candidates.add(
+                    (min(other_index, current_index), max(other_index, current_index))
+                )
+        active.append(current_index)
+
+    nonsweepable = numeric - sweepable
+    for first_index in sorted(nonsweepable):
+        for second_index in sorted(numeric):
+            if first_index < second_index:
+                candidates.add((first_index, second_index))
+            elif second_index < first_index and second_index in sweepable:
+                candidates.add((second_index, first_index))
+    return sorted(candidates)
+
+
+def verify_nest_placements(
+    plate_reports: list[dict[str, Any]],
+    *,
+    edge_margin: float,
+    inter_part_clearance: float,
+) -> list[dict[str, Any]]:
+    """Verify normalized placements without relying on a packing algorithm's state."""
+    findings: list[dict[str, Any]] = []
+    epsilon = 1e-9
+    for plate_index, plate in enumerate(plate_reports):
+        usable_width = plate.get("W", 0) - 2 * edge_margin
+        usable_height = plate.get("H", 0) - 2 * edge_margin
+        placements = plate.get("placements", [])
+        plate_basis = (
+            plate.get("material"),
+            plate.get("grade"),
+            plate.get("thickness"),
+        )
+        for placement_index, placement in enumerate(placements):
+            path = f"$.plate_reports[{plate_index}].placements[{placement_index}]"
+            values = (
+                placement.get("x"),
+                placement.get("y"),
+                placement.get("w"),
+                placement.get("h"),
+            )
+            if not all(
+                isinstance(value, (int, float))
+                and not isinstance(value, bool)
+                and math.isfinite(value)
+                for value in values
+            ):
+                findings.append(
+                    {
+                        "code": "nonfinite_placement",
+                        "path": path,
+                        "message": "Placement coordinates and dimensions must be finite.",
+                    }
+                )
+                continue
+            x, y, width, height = values
+            if (
+                width <= 0
+                or height <= 0
+                or x < -epsilon
+                or y < -epsilon
+                or x + width > usable_width + epsilon
+                or y + height > usable_height + epsilon
+            ):
+                findings.append(
+                    {
+                        "code": "placement_out_of_bounds",
+                        "path": path,
+                        "message": "Placement must remain inside the edge-margin boundary.",
+                    }
+                )
+            placement_basis = (
+                placement.get("material"),
+                placement.get("grade"),
+                placement.get("thickness"),
+            )
+            if placement_basis != plate_basis:
+                findings.append(
+                    {
+                        "code": "material_mismatch",
+                        "path": path,
+                        "message": "Placement material, grade, and thickness must match its stock.",
+                    }
+                )
+
+        for first_index, second_index in _overlap_candidate_pairs(
+            placements, inter_part_clearance, epsilon
+        ):
+            first = placements[first_index]
+            second = placements[second_index]
+            if not _placements_separated(
+                first, second, inter_part_clearance, epsilon
+            ):
+                findings.append(
+                    {
+                        "code": "placement_overlap",
+                        "path": (
+                            f"$.plate_reports[{plate_index}].placements"
+                            f"[{first_index},{second_index}]"
+                        ),
+                        "message": (
+                            "Placements overlap or violate the required "
+                            "kerf-plus-gap clearance."
+                        ),
+                    }
+                )
+    return findings